@webority/mobile-ui 0.0.0-stage → 0.0.34

package/lib/commonjs/form/useForm.js

@@ -0,0 +1,364 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useForm = useForm;
+var _react = require("react");
+var _path = require("./path.js");
+// Loosely typed (Values -> any) so the generic schema from any useForm<Values>
+// instance flows in without variance friction; callers re-apply Values at use.
+const rulesFor = (validate, name) => {
+  if (!validate || typeof validate === 'function') {
+    return [];
+  }
+  const r = validate[name];
+  if (!r) {
+    return [];
+  }
+  return Array.isArray(r) ? r : [r];
+};
+
+/**
+ * Dependency-free form engine. Tracks values/errors/touched/dirty, runs
+ * synchronous and async validation (per-field rule maps or a form-level
+ * function), gates error display behind touched/submit, and on a failed submit
+ * focuses the first errored field. The returned object is rebuilt every render
+ * so `<Form>` consumers re-render on state changes.
+ */
+function useForm(config) {
+  const configRef = (0, _react.useRef)(config);
+  configRef.current = config;
+  const initialRef = (0, _react.useRef)(config.initialValues);
+  const [values, setValuesState] = (0, _react.useState)(config.initialValues);
+  const [errors, setErrorsState] = (0, _react.useState)({});
+  const [touched, setTouchedState] = (0, _react.useState)({});
+  const [isSubmitting, setSubmitting] = (0, _react.useState)(false);
+  const [isValidating, setValidating] = (0, _react.useState)(false);
+  const [submitCount, setSubmitCount] = (0, _react.useState)(0);
+
+  // Mirror of the latest state so handlers (incl. async) never read stale
+  // closures and sequential setFieldValue calls in one tick compound correctly.
+  const ref = (0, _react.useRef)({
+    values,
+    errors,
+    touched,
+    submitCount
+  });
+  ref.current = {
+    values,
+    errors,
+    touched,
+    submitCount
+  };
+  const fieldNodes = (0, _react.useRef)(new Map());
+  const fieldOrder = (0, _react.useRef)([]);
+  const focusedFieldRef = (0, _react.useRef)(null);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `JSON.stringify(config.initialValues)` is the dependency by design so reinitialize compares by value, not by object identity
+  (0, _react.useEffect)(() => {
+    if (!configRef.current.enableReinitialize) {
+      return;
+    }
+    const next = configRef.current.initialValues;
+    initialRef.current = next;
+    ref.current.values = next;
+    ref.current.errors = {};
+    ref.current.touched = {};
+    setValuesState(next);
+    setErrorsState({});
+    setTouchedState({});
+  }, [JSON.stringify(config.initialValues)]);
+  const validateField = (0, _react.useCallback)(async name => {
+    const validate = configRef.current.validate;
+    const allValues = ref.current.values;
+    if (typeof validate === 'function') {
+      const map = (await validate(allValues)) ?? {};
+      return map[name] || undefined;
+    }
+    const value = (0, _path.getPath)(allValues, name);
+    for (const rule of rulesFor(validate, name)) {
+      const res = await rule(value, allValues);
+      if (res) {
+        return res;
+      }
+    }
+    return undefined;
+  }, []);
+  const runAll = (0, _react.useCallback)(async vals => {
+    const validate = configRef.current.validate;
+    if (!validate) {
+      return {};
+    }
+    if (typeof validate === 'function') {
+      return (await validate(vals)) ?? {};
+    }
+    const out = {};
+    await Promise.all(Object.keys(validate).map(async name => {
+      const value = (0, _path.getPath)(vals, name);
+      for (const rule of rulesFor(validate, name)) {
+        const res = await rule(value, vals);
+        if (res) {
+          out[name] = res;
+          break;
+        }
+      }
+    }));
+    return out;
+  }, []);
+  const revalidateField = (0, _react.useCallback)(async name => {
+    const err = await validateField(name);
+    setErrorsState(prev => {
+      if (prev[name] === err) {
+        return prev;
+      }
+      const next = {
+        ...prev
+      };
+      if (err) {
+        next[name] = err;
+      } else {
+        delete next[name];
+      }
+      ref.current.errors = next;
+      return next;
+    });
+  }, [validateField]);
+  const validate = (0, _react.useCallback)(async () => {
+    setValidating(true);
+    const errs = await runAll(ref.current.values);
+    setValidating(false);
+    ref.current.errors = errs;
+    setErrorsState(errs);
+    return errs;
+  }, [runAll]);
+  const setFieldValue = (0, _react.useCallback)((name, value, shouldValidate) => {
+    const next = (0, _path.setPath)(ref.current.values, name, value);
+    ref.current.values = next;
+    setValuesState(next);
+    const cfg = configRef.current;
+    // `revalidateOn: 'blur'` means a field that has ALREADY surfaced an error
+    // stops re-checking on every keystroke and waits for blur — without this
+    // the option was declared, documented and ignored.
+    const alreadyErrored = Boolean(ref.current.errors[name]);
+    const deferToBlur = alreadyErrored && cfg.revalidateOn === 'blur';
+    const willValidate = shouldValidate ?? (!deferToBlur && (ref.current.touched[name] || ref.current.submitCount > 0 || cfg.validateOn === 'change'));
+    if (willValidate) {
+      void revalidateField(name);
+    }
+  }, [revalidateField]);
+  const handleBlur = (0, _react.useCallback)(name => {
+    setTouchedState(prev => {
+      if (prev[name]) {
+        return prev;
+      }
+      const next = {
+        ...prev,
+        [name]: true
+      };
+      ref.current.touched = next;
+      return next;
+    });
+    // Blur is the natural moment to surface a field's error.
+    void revalidateField(name);
+  }, [revalidateField]);
+  const setFieldTouched = (0, _react.useCallback)((name, isTouched = true, shouldValidate) => {
+    const next = {
+      ...ref.current.touched,
+      [name]: isTouched
+    };
+    ref.current.touched = next;
+    setTouchedState(next);
+    if (shouldValidate ?? isTouched) {
+      void revalidateField(name);
+    }
+  }, [revalidateField]);
+  const setFieldError = (0, _react.useCallback)((name, error) => {
+    setErrorsState(prev => {
+      const next = {
+        ...prev
+      };
+      if (error) {
+        next[name] = error;
+      } else {
+        delete next[name];
+      }
+      ref.current.errors = next;
+      return next;
+    });
+  }, []);
+  const setErrors = (0, _react.useCallback)(errs => {
+    ref.current.errors = errs;
+    setErrorsState(errs);
+  }, []);
+  const setValues = (0, _react.useCallback)((next, shouldValidate) => {
+    const resolved = typeof next === 'function' ? next(ref.current.values) : {
+      ...ref.current.values,
+      ...next
+    };
+    ref.current.values = resolved;
+    setValuesState(resolved);
+    if (shouldValidate) {
+      void validate();
+    }
+  }, [validate]);
+  const reset = (0, _react.useCallback)(nextValues => {
+    const base = nextValues ? {
+      ...initialRef.current,
+      ...nextValues
+    } : initialRef.current;
+    initialRef.current = base;
+    ref.current.values = base;
+    ref.current.errors = {};
+    ref.current.touched = {};
+    ref.current.submitCount = 0;
+    setValuesState(base);
+    setErrorsState({});
+    setTouchedState({});
+    setSubmitCount(0);
+  }, []);
+  const registerField = (0, _react.useCallback)((name, node) => {
+    if (node) {
+      fieldNodes.current.set(name, node);
+      if (!fieldOrder.current.includes(name)) {
+        fieldOrder.current.push(name);
+      }
+    } else {
+      fieldNodes.current.delete(name);
+      fieldOrder.current = fieldOrder.current.filter(n => n !== name);
+    }
+  }, []);
+  const handleFocus = (0, _react.useCallback)(name => {
+    focusedFieldRef.current = name;
+  }, []);
+  const focusAdjacent = (0, _react.useCallback)(direction => {
+    const order = fieldOrder.current;
+    const current = focusedFieldRef.current;
+    const index = current ? order.indexOf(current) : -1;
+    const target = order[index + direction];
+    if (!target) {
+      return;
+    }
+    focusedFieldRef.current = target;
+    fieldNodes.current.get(target)?.focus?.();
+  }, []);
+  const focusNext = (0, _react.useCallback)(() => focusAdjacent(1), [focusAdjacent]);
+  const focusPrev = (0, _react.useCallback)(() => focusAdjacent(-1), [focusAdjacent]);
+  const helpers = (0, _react.useMemo)(() => ({
+    setErrors,
+    setFieldError,
+    reset,
+    setSubmitting
+  }), [setErrors, setFieldError, reset]);
+  const submit = (0, _react.useCallback)(() => {
+    void (async () => {
+      const cfg = configRef.current;
+      const currentValues = ref.current.values;
+      ref.current.submitCount += 1;
+      setSubmitCount(c => c + 1);
+      setValidating(true);
+      const errs = await runAll(currentValues);
+      setValidating(false);
+      const keys = new Set([...fieldOrder.current, ...Object.keys(errs)]);
+      const nextTouched = {
+        ...ref.current.touched
+      };
+      keys.forEach(k => {
+        nextTouched[k] = true;
+      });
+      ref.current.touched = nextTouched;
+      ref.current.errors = errs;
+      setTouchedState(nextTouched);
+      setErrorsState(errs);
+      const firstError = fieldOrder.current.find(n => errs[n]) ?? Object.keys(errs).find(n => errs[n]);
+      if (firstError) {
+        fieldNodes.current.get(firstError)?.focus?.();
+        return;
+      }
+      setSubmitting(true);
+      try {
+        await cfg.onSubmit(currentValues, helpers);
+      } finally {
+        setSubmitting(false);
+      }
+    })();
+  }, [runAll, helpers]);
+  const uiErrors = (0, _react.useMemo)(() => {
+    const gated = {};
+    for (const k of Object.keys(errors)) {
+      if (errors[k] && (touched[k] || submitCount > 0)) {
+        gated[k] = errors[k];
+      }
+    }
+    return gated;
+  }, [errors, touched, submitCount]);
+  const isValid = (0, _react.useMemo)(() => {
+    const validateCfg = configRef.current.validate;
+    if (!validateCfg) {
+      return true;
+    }
+    // Form-level async fn can't run synchronously — fall back to known errors.
+    if (typeof validateCfg === 'function') {
+      return Object.values(errors).every(e => !e);
+    }
+    for (const name of Object.keys(validateCfg)) {
+      const value = (0, _path.getPath)(values, name);
+      for (const rule of rulesFor(validateCfg, name)) {
+        const res = rule(value, values);
+        if (typeof res === 'string' && res) {
+          return false; // async rules (Promise) are skipped here
+        }
+      }
+    }
+    return true;
+  }, [values, errors]);
+  const dirty = (0, _react.useMemo)(() => JSON.stringify(values) !== JSON.stringify(initialRef.current), [values]);
+  return {
+    values,
+    errors: uiErrors,
+    rawErrors: errors,
+    touched,
+    dirty,
+    isValid,
+    isSubmitting,
+    isValidating,
+    submitCount,
+    setFieldValue,
+    setFieldTouched,
+    setFieldError,
+    setValues,
+    setErrors,
+    reset,
+    validate,
+    validateField,
+    submit,
+    handleBlur,
+    focusNext,
+    focusPrev,
+    registerField,
+    getFieldState: name => {
+      const value = (0, _path.getPath)(values, name);
+      const rawError = errors[name];
+      const isTouched = !!touched[name];
+      return {
+        value,
+        error: isTouched || submitCount > 0 ? rawError : undefined,
+        rawError,
+        touched: isTouched,
+        dirty: JSON.stringify(value) !== JSON.stringify((0, _path.getPath)(initialRef.current, name))
+      };
+    },
+    getFieldProps: name => ({
+      name,
+      value: (0, _path.getPath)(values, name),
+      error: touched[name] || submitCount > 0 ? errors[name] : undefined,
+      touched: !!touched[name],
+      onChange: val => setFieldValue(name, val),
+      onChangeText: text => setFieldValue(name, text),
+      onBlur: () => handleBlur(name),
+      onFocus: () => handleFocus(name),
+      setValue: (val, sv) => setFieldValue(name, val, sv)
+    })
+  };
+}
+//# sourceMappingURL=useForm.js.map

package/lib/commonjs/form/useFormCompletion.js

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useFormCompletion = exports.isFieldFilled = void 0;
+var _react = require("react");
+var _path = require("./path.js");
+/**
+ * The default rule for "this field holds a value": everything counts except
+ * `undefined`, `null`, `NaN`, a string that is empty or only whitespace, an
+ * empty array, and `false`. `false` is empty on purpose: a field is listed
+ * because completing the profile needs it, and for a switch or a checkbox
+ * that means it must be on ("accept the terms"). An optional toggle should
+ * not be listed. `0` is a value.
+ */
+const isFieldFilled = value => {
+  if (value === undefined || value === null || value === false) {
+    return false;
+  }
+  if (typeof value === 'number') {
+    return !Number.isNaN(value);
+  }
+  if (typeof value === 'string') {
+    return value.trim().length > 0;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  return true;
+};
+
+/**
+ * How much of a form is filled in: `progress` as a fraction for a
+ * ProgressRing, `percent` for a ProfileCompletion header. Give it the form's `values` and the
+ * names of the fields that count; nested names (`address.city`, `phones[0]`)
+ * resolve the way the form engine's own paths do.
+ *
+ * ```tsx
+ * const form = useForm({ initialValues });
+ * const { percent } = useFormCompletion(form.values, ['name', 'email', 'gstin']);
+ * <ProfileCompletion progress={percent} … />
+ * ```
+ *
+ * Memoised on the values object and on the field list's contents, so a
+ * literal array written in render does not recompute on every render.
+ */
+exports.isFieldFilled = isFieldFilled;
+const useFormCompletion = (values, fields, options = {}) => {
+  const {
+    isFilled
+  } = options;
+  const fieldKey = fields.join('\u0000');
+  return (0, _react.useMemo)(() => {
+    const names = fieldKey.length === 0 ? [] : fieldKey.split('\u0000');
+    const missing = names.filter(name => {
+      const value = (0, _path.getPath)(values, name);
+      return !(isFilled ? isFilled(value, name) : isFieldFilled(value));
+    });
+    const total = names.length;
+    const filled = total - missing.length;
+    const progress = total === 0 ? 0 : filled / total;
+    return {
+      progress,
+      percent: progress * 100,
+      filled,
+      total,
+      missing
+    };
+  }, [values, fieldKey, isFilled]);
+};
+exports.useFormCompletion = useFormCompletion;
+//# sourceMappingURL=useFormCompletion.js.map

package/lib/commonjs/hooks/index.js

@@ -0,0 +1,85 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "DRAG_DISMISS_DISTANCE", {
+  enumerable: true,
+  get: function () {
+    return _useDragToDismiss.DRAG_DISMISS_DISTANCE;
+  }
+});
+Object.defineProperty(exports, "DRAG_DISMISS_VELOCITY", {
+  enumerable: true,
+  get: function () {
+    return _useDragToDismiss.DRAG_DISMISS_VELOCITY;
+  }
+});
+Object.defineProperty(exports, "FLICK_TOLERANCE", {
+  enumerable: true,
+  get: function () {
+    return _useFlickGuard.FLICK_TOLERANCE;
+  }
+});
+Object.defineProperty(exports, "PRESS_ANIMATION_PRESETS", {
+  enumerable: true,
+  get: function () {
+    return _usePressAnimation.PRESS_ANIMATION_PRESETS;
+  }
+});
+Object.defineProperty(exports, "createDragToDismissController", {
+  enumerable: true,
+  get: function () {
+    return _useDragToDismiss.createDragToDismissController;
+  }
+});
+Object.defineProperty(exports, "useControllableState", {
+  enumerable: true,
+  get: function () {
+    return _useControllableState.useControllableState;
+  }
+});
+Object.defineProperty(exports, "useDebounce", {
+  enumerable: true,
+  get: function () {
+    return _useDebounce.useDebounce;
+  }
+});
+Object.defineProperty(exports, "useDragToDismiss", {
+  enumerable: true,
+  get: function () {
+    return _useDragToDismiss.useDragToDismiss;
+  }
+});
+Object.defineProperty(exports, "useFlickGuard", {
+  enumerable: true,
+  get: function () {
+    return _useFlickGuard.useFlickGuard;
+  }
+});
+Object.defineProperty(exports, "usePressAnimation", {
+  enumerable: true,
+  get: function () {
+    return _usePressAnimation.usePressAnimation;
+  }
+});
+Object.defineProperty(exports, "useReducedMotion", {
+  enumerable: true,
+  get: function () {
+    return _useReducedMotion.useReducedMotion;
+  }
+});
+Object.defineProperty(exports, "useToggle", {
+  enumerable: true,
+  get: function () {
+    return _useToggle.useToggle;
+  }
+});
+var _useControllableState = require("./useControllableState.js");
+var _useDebounce = require("./useDebounce.js");
+var _useDragToDismiss = require("./useDragToDismiss.js");
+var _useFlickGuard = require("./useFlickGuard.js");
+var _usePressAnimation = require("./usePressAnimation.js");
+var _useReducedMotion = require("./useReducedMotion.js");
+var _useToggle = require("./useToggle.js");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/hooks/useControllableState.js

@@ -0,0 +1,32 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useControllableState = useControllableState;
+var _react = require("react");
+/**
+ * Bridges controlled and uncontrolled usage for a value+onChange pair. When
+ * `value` is provided the component is controlled (the hook just forwards it
+ * and calls `onChange`); otherwise the hook owns the state, seeded from
+ * `defaultValue`. The controlled/uncontrolled decision is locked on first
+ * render so a component never flips modes mid-life.
+ */
+function useControllableState({
+  value,
+  defaultValue,
+  onChange
+}) {
+  const isControlledRef = (0, _react.useRef)(value !== undefined);
+  const isControlled = isControlledRef.current;
+  const [internal, setInternal] = (0, _react.useState)(defaultValue);
+  const current = isControlled ? value : internal;
+  const setValue = (0, _react.useCallback)(next => {
+    if (!isControlled) {
+      setInternal(next);
+    }
+    onChange?.(next);
+  }, [isControlled, onChange]);
+  return [current, setValue];
+}
+//# sourceMappingURL=useControllableState.js.map

package/lib/commonjs/hooks/useDebounce.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useDebounce = void 0;
+var _react = require("react");
+const useDebounce = (value, delay = 300) => {
+  const [debounced, setDebounced] = (0, _react.useState)(value);
+  (0, _react.useEffect)(() => {
+    const handle = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(handle);
+  }, [value, delay]);
+  return debounced;
+};
+exports.useDebounce = useDebounce;
+//# sourceMappingURL=useDebounce.js.map