panelui-native 0.35.2 → 0.38.0

package/src/components/form/use-field.ts

@@ -47,6 +47,29 @@ export function useField<T extends Record<string, any>, K extends keyof T>(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [registerValidator, name, !!validate]);
 
+  /*
+   * A name the form never declared is the one mistake this hook cannot
+   * recover from: there is no value to hand a validator, so a rule as ordinary
+   * as `value.length > 0` throws on a field that was only blurred, and nothing
+   * the user types is ever submitted. Both failures point away from the cause,
+   * so it is named here instead. Development only — the check costs a key
+   * lookup, but the message is for whoever is writing the form.
+   */
+  const formValues = form.values;
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    if (name in formValues) return;
+    console.warn(
+      `[PanelUI] Form field "${String(name)}" is not declared in the form's ` +
+        `defaultValues, so its value is undefined and it will not be submitted. ` +
+        `Add "${String(name)}" to defaultValues — an empty field is still a ` +
+        `declared one ("" for text, false for a toggle).`
+    );
+    // The declared names come from `defaultValues`, which is read once, so
+    // this is a question about the name and nothing else.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [name]);
+
   const { value, error, touched } = form.getFieldState(name);
 
   return {

package/src/components/form/use-form.ts

@@ -24,6 +24,12 @@
  * `defaultValues` is read once, on the first render. If default values
  * arrive asynchronously, mount the form once you have them (e.g. behind a
  * loading check) rather than expecting the hook to pick up a later change.
+ *
+ * It also declares the fields. A field's `name` has to be a key of it —
+ * including the empty ones, as `''`, `false`, `null`. A name it does not
+ * declare has no value to give a validator and nothing to submit, so
+ * `useField` says so in development rather than letting the field quietly do
+ * nothing.
  */
 import { useCallback, useMemo, useReducer, useRef } from 'react';
 
@@ -123,6 +129,42 @@ function reducer<T extends Record<string, any>>(
   }
 }
 
+/** Stands in for the message a rule that crashed never got to return. */
+const VALIDATOR_THREW = 'This field could not be validated.';
+
+/**
+ * Run one field's rule, and survive a rule that throws.
+ *
+ * A validator is caller code reached from a path nothing awaits — `onBlur`
+ * fires and forgets, and `handleSubmit` is wired straight to a press. A throw
+ * in there becomes an unhandled rejection: a red box whose message ("cannot
+ * read property 'length' of undefined") names neither the field nor the rule,
+ * and which takes the screen for one line of one validator.
+ *
+ * So it is caught, reported against the field by name, and counted as a
+ * failure. Counted, rather than waved through: a rule that crashed reached no
+ * verdict, and a form that submits past a rule that never ran is the worse of
+ * the two outcomes — it puts unchecked values somewhere they cannot be taken
+ * back from. The placeholder message is what stands between the two; the
+ * console entry beside it is for whoever can fix the rule.
+ */
+async function runValidator<T extends Record<string, any>>(
+  name: keyof T,
+  validator: (value: any, values: T) => string | undefined | Promise<string | undefined>,
+  values: T
+): Promise<string | undefined> {
+  try {
+    return await validator(values[name], values);
+  } catch (error) {
+    console.error(
+      `[PanelUI] The validator for form field "${String(name)}" threw, so the ` +
+        `field is being treated as invalid.`,
+      error
+    );
+    return VALIDATOR_THREW;
+  }
+}
+
 export function useForm<T extends Record<string, any>>({
   defaultValues,
   validate,
@@ -140,7 +182,22 @@ export function useForm<T extends Record<string, any>>({
     isSubmitting: false,
   });
 
+  /*
+   * The values as of the last *change*, not as of the last render.
+   *
+   * Validation runs in the same tick as the edit that triggered it —
+   * `validateOn="change"` calls `validateField` immediately after
+   * `setFieldValue`, and submit runs from a press handler. React state is a
+   * render behind at that point, so a validator reading it would judge the
+   * character before the one just typed, and a submit fired straight after an
+   * edit would submit the value before it. The ref is written on the way into
+   * the dispatch so both see what the user actually entered.
+   */
+  const valuesRef = useRef(state.values);
+  valuesRef.current = state.values;
+
   const setFieldValue = useCallback(<K extends keyof T>(name: K, value: T[K]) => {
+    valuesRef.current = { ...valuesRef.current, [name]: value } as T;
     dispatch({ type: 'SET_VALUE', name, value });
   }, []);
 
@@ -175,32 +232,64 @@ export function useForm<T extends Record<string, any>>({
     [state.values, state.errors, state.touched]
   );
 
-  const validateField = useCallback(
-    async <K extends keyof T>(name: K) => {
-      const validator = validatorsRef.current[name];
-      if (!validator) return true;
-      const error = await validator(state.values[name], state.values);
-      dispatch({ type: 'SET_ERROR', name, error });
-      return !error;
-    },
-    [state.values]
-  );
+  const validateField = useCallback(async <K extends keyof T>(name: K) => {
+    const validator = validatorsRef.current[name];
+    if (!validator) return true;
+    const values = valuesRef.current;
+    const error = await runValidator(name, validator, values);
+    dispatch({ type: 'SET_ERROR', name, error });
+    return !error;
+  }, []);
 
   const handleSubmit = useCallback(async () => {
-    const names = Object.keys(state.values) as (keyof T)[];
+    const values = valuesRef.current;
+    /*
+     * Every field the form knows of, which is not the same as every key of
+     * `defaultValues`: a field can register a validator under a name that was
+     * never declared there. Submitting only the declared ones meant such a
+     * field was never validated and never blocked anything, so a form of
+     * required-but-undeclared fields submitted itself while still empty.
+     *
+     * It is still a mistake to name a field that `defaultValues` does not
+     * declare — its value stays undefined and never reaches `onSubmit` —
+     * which is why `useField` says so. Validating it anyway is what turns
+     * that mistake into a visible error instead of a silent submit.
+     */
+    const names = Array.from(
+      new Set([...Object.keys(values), ...Object.keys(validatorsRef.current)])
+    ) as (keyof T)[];
     dispatch({ type: 'TOUCH_ALL', names });
 
     const fieldErrorEntries = await Promise.all(
       names.map(async (name) => {
         const validator = validatorsRef.current[name];
         const error = validator
-          ? await validator(state.values[name], state.values)
+          ? await runValidator(name, validator, values)
           : undefined;
         return [name, error] as const;
       })
     );
 
-    const formErrors = validate ? await validate(state.values) : {};
+    /*
+     * Same reasoning as a field's rule, one level up: a cross-field check that
+     * throws must not take the screen, and must not let the submit through.
+     * It belongs to no single field, so it blocks without marking one — there
+     * is no field whose error line would be the honest place to put it.
+     */
+    let formErrors: FieldErrors<T> = {};
+    let formValidateThrew = false;
+    if (validate) {
+      try {
+        formErrors = await validate(values);
+      } catch (error) {
+        console.error(
+          '[PanelUI] The form-level validate() threw, so the form is being ' +
+            'treated as invalid and the submit was not run.',
+          error
+        );
+        formValidateThrew = true;
+      }
+    }
 
     const cleared = Object.fromEntries(names.map((name) => [name, undefined]));
     const nextErrors: FieldErrors<T> = {
@@ -210,17 +299,18 @@ export function useForm<T extends Record<string, any>>({
     };
     dispatch({ type: 'SET_ERRORS', errors: nextErrors });
 
-    if (Object.values(nextErrors).some(Boolean)) return;
+    if (formValidateThrew || Object.values(nextErrors).some(Boolean)) return;
 
     dispatch({ type: 'SUBMIT_START' });
     try {
-      await onSubmit(state.values);
+      await onSubmit(values);
     } finally {
       dispatch({ type: 'SUBMIT_END' });
     }
-  }, [state.values, validate, onSubmit]);
+  }, [validate, onSubmit]);
 
   const reset = useCallback((values: T = defaultsRef.current) => {
+    valuesRef.current = values;
     dispatch({ type: 'RESET', values });
   }, []);
 

package/src/components/input/index.tsx

@@ -14,13 +14,38 @@
  * ```tsx
  * <Input label="Email" placeholder="you@example.com" />
  * <Input variant="filled" size="lg" label="Name" isRequired />
+ * <Input label="Note" startContent={<PencilIcon size={18} />} />
  * ```
  *
- * For a field with an icon or a button attached, reach for `InputGroup` — it
- * measures its decorators and pads this field around them.
+ * ## An icon inside the field, and why it lives here
+ *
+ * `startContent` and `endContent` are measured and turned into padding on the
+ * text, so a value never runs underneath them however wide they turn out to
+ * be. They are positioned against the *field box* rather than against the
+ * component, which is the whole reason they are a prop rather than something
+ * you compose: a label and a description are laid out above and below the
+ * field, so anything centred on the component as a whole drifts upward the
+ * moment a label is added.
+ *
+ * Both are pressable. A button dropped in there — a clear ✕, a show-password
+ * eye — gets its own touches, while the padding around it stays transparent so
+ * a tap that misses still lands on the field and puts the caret in it. An icon
+ * that is only decoration should say so with `interactiveContent={false}`,
+ * which gives the whole field back to the caret and takes the icon out of the
+ * accessibility tree.
+ *
+ * `InputGroup` is still the right answer for a decorator that is not part of
+ * the field — a button attached to its end, a select bolted to its start, an
+ * addon with its own background. It measures the same way; it just spans a
+ * different box.
  */
-import { forwardRef, useCallback, useEffect, useState } from 'react';
-import { TextInput, View, type TextInputProps } from 'react-native';
+import { forwardRef, useCallback, useEffect, useState, type ReactNode } from 'react';
+import {
+  TextInput,
+  View,
+  type LayoutChangeEvent,
+  type TextInputProps,
+} from 'react-native';
 import Animated, {
   interpolateColor,
   useAnimatedStyle,
@@ -30,8 +55,9 @@ import Animated, {
 import { tv, type VariantProps } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import type { KeyboardAvoidanceMode } from '../../hooks/use-keyboard-avoidance';
+import { IconColorProvider } from '../../icons';
 import { KeyboardAvoider } from '../../primitives/keyboard-avoider';
-import { Text } from '../../primitives/text';
+import { Text, textChildren } from '../../primitives/text';
 import { Label } from '../label';
 
 /** Long enough to read as a transition, short enough not to lag a fast tab. */
@@ -40,9 +66,25 @@ const FOCUS_DURATION = 150;
 const inputVariants = tv({
   slots: {
     container: 'w-full gap-1.5',
-    field: 'w-full rounded-lg border text-foreground',
+    /*
+     * `font-normal` on a field that is not bold: this is a TextInput, so it
+     * does not go through the Text primitive and inherits nothing. The class
+     * is what an app's `--font-normal` token attaches to, and without it a
+     * custom font would stop at the edge of every field in the library.
+     */
+    field: 'w-full rounded-lg border font-normal text-foreground',
     description: 'text-sm text-muted-foreground',
     error: 'text-sm text-destructive',
+    /*
+     * The box the content is positioned against, and the reason this works
+     * where wrapping the whole component does not: it is the field alone, so
+     * a label above it and a description below it cannot move what is inside.
+     */
+    fieldBox: 'relative w-full',
+    startContent:
+      'absolute bottom-0 start-0 top-0 z-10 flex-row items-center justify-center gap-2',
+    endContent:
+      'absolute bottom-0 end-0 top-0 z-10 flex-row items-center justify-center gap-2',
   },
   variants: {
     variant: {
@@ -60,19 +102,33 @@ const inputVariants = tv({
        * below the middle of the box, a few pixels off whatever is beside them.
        * A length sets the size alone and leaves the line box the font's own.
        */
-      sm: { field: 'h-10 px-3 text-[14px]' },
-      md: { field: 'h-12 px-3.5 text-[16px]' },
-      lg: { field: 'h-14 px-4 text-[16px]' },
+      // The content boxes take the field's own horizontal padding, so an icon
+      // sits at exactly the inset the text would have started at.
+      sm: { field: 'h-10 px-3 text-[14px]', startContent: 'px-3', endContent: 'px-3' },
+      md: { field: 'h-12 px-3.5 text-[16px]', startContent: 'px-3.5', endContent: 'px-3.5' },
+      lg: { field: 'h-14 px-4 text-[16px]', startContent: 'px-4', endContent: 'px-4' },
     },
     multiline: {
       // A multiline field grows, so a fixed height would crop it. Text starts
       // at the top rather than floating in the middle of an empty box — and
       // once there are several lines the leading is wanted back, since here it
       // separates the lines instead of pushing one off centre.
-      true: { field: 'h-auto min-h-24 py-3 leading-normal' },
+      //
+      // The content follows the text to the top for the same reason: centred
+      // in a box that grows, an icon slides further from the line it belongs
+      // to with every line typed.
+      true: {
+        field: 'h-auto min-h-24 py-3 leading-normal',
+        startContent: 'bottom-auto py-3',
+        endContent: 'bottom-auto py-3',
+      },
     },
     disabled: {
-      true: { field: 'opacity-[0.64]' },
+      true: {
+        field: 'opacity-[0.64]',
+        startContent: 'opacity-[0.64]',
+        endContent: 'opacity-[0.64]',
+      },
     },
   },
   defaultVariants: {
@@ -95,6 +151,31 @@ export interface InputProps
   /** Marks the field required — an asterisk on the label, and the a11y state. */
   isRequired?: boolean;
   disabled?: boolean;
+  /**
+   * Content inside the field, before the text — usually an icon. Measured, so
+   * the text is padded clear of it however wide it is.
+   *
+   * `start`, not `left`: it follows the reading direction, and swaps sides
+   * under `Direction dir="rtl"` along with the text it introduces.
+   */
+  startContent?: ReactNode;
+  /** Content inside the field, after the text — an icon, a unit, a count. */
+  endContent?: ReactNode;
+  /**
+   * Whether touches reach the content.
+   *
+   * On by default, so a button placed in the field — a clear ✕, a
+   * show-password eye, a unit picker — is pressable without anything else
+   * being passed. Only the content itself takes those touches: the padding
+   * around it is transparent, so a tap that misses the button still lands on
+   * the field and puts the caret in it.
+   *
+   * Turn it off for pure decoration, where the icon should not be a target at
+   * all and every pixel of the field should focus it. That also drops the
+   * content from the accessibility tree, which is right for an icon that only
+   * restates the label.
+   */
+  interactiveContent?: boolean;
   /**
    * Keep the field clear of the software keyboard. Moves by exactly the
    * overlap, and not at all when the field is already clear — or when the
@@ -136,6 +217,9 @@ export const Input = forwardRef<TextInput, InputProps>(
       errorMessage,
       isRequired,
       disabled,
+      startContent,
+      endContent,
+      interactiveContent = true,
       variant,
       size,
       avoidKeyboard = false,
@@ -151,6 +235,10 @@ export const Input = forwardRef<TextInput, InputProps>(
   ) => {
     const [focused, setFocused] = useState(false);
     const invalid = !!errorMessage;
+    // Measured so the text can be padded clear of the content, whatever it
+    // turns out to be — an icon, a unit, a two-word label.
+    const [startWidth, setStartWidth] = useState(0);
+    const [endWidth, setEndWidth] = useState(0);
 
     const placeholderColor = useCSSVariable('--color-muted-foreground');
     const restColor = useCSSVariable('--color-input');
@@ -207,6 +295,49 @@ export const Input = forwardRef<TextInput, InputProps>(
       [onBlur]
     );
 
+    const handleStartLayout = useCallback((event: LayoutChangeEvent) => {
+      setStartWidth(event.nativeEvent.layout.width);
+    }, []);
+
+    const handleEndLayout = useCallback((event: LayoutChangeEvent) => {
+      setEndWidth(event.nativeEvent.layout.width);
+    }, []);
+
+    /*
+     * The content is quieter than the value. An icon at the same weight as the
+     * text reads as part of what was typed, and the placeholder colour is
+     * already the field's own word for "not the value".
+     */
+    const iconColor = typeof placeholderColor === 'string' ? placeholderColor : undefined;
+
+    const field = (
+      <AnimatedTextInput
+        ref={ref}
+        editable={!disabled}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        accessibilityLabel={label}
+        accessibilityState={{ disabled: !!disabled }}
+        aria-required={isRequired}
+        aria-invalid={invalid}
+        className={slots.field({ className })}
+        style={[
+          borderStyle,
+          // Only the side that has content, and only once it has been
+          // measured — a 0 here would wipe out the field's own padding.
+          startWidth ? { paddingStart: startWidth } : null,
+          endWidth ? { paddingEnd: endWidth } : null,
+          // Caller styles come last so InputGroup can pad the field around its
+          // decorators, but never last enough to drop the animated border.
+          style,
+        ]}
+        placeholderTextColor={
+          typeof placeholderColor === 'string' ? placeholderColor : undefined
+        }
+        {...props}
+      />
+    );
+
     const body = (
       <>
         {label ? (
@@ -214,24 +345,49 @@ export const Input = forwardRef<TextInput, InputProps>(
             {label}
           </Label>
         ) : null}
-        <AnimatedTextInput
-          ref={ref}
-          editable={!disabled}
-          onFocus={handleFocus}
-          onBlur={handleBlur}
-          accessibilityLabel={label}
-          accessibilityState={{ disabled: !!disabled }}
-          aria-required={isRequired}
-          aria-invalid={invalid}
-          className={slots.field({ className })}
-          // Caller styles come last so InputGroup can pad the field around its
-          // decorators, but never last enough to drop the animated border.
-          style={[borderStyle, style]}
-          placeholderTextColor={
-            typeof placeholderColor === 'string' ? placeholderColor : undefined
-          }
-          {...props}
-        />
+        {startContent || endContent ? (
+          /*
+           * Only wrapped when there is something to position. An extra view
+           * around every field in an app is a real cost in a long form, and
+           * the field is `w-full` either way so the wrapper changes nothing
+           * else about the layout.
+           */
+          <View className={slots.fieldBox()}>
+            {startContent ? (
+              <View
+                onLayout={handleStartLayout}
+                pointerEvents={interactiveContent ? 'box-none' : 'none'}
+                accessibilityElementsHidden={!interactiveContent}
+                importantForAccessibility={
+                  interactiveContent ? 'auto' : 'no-hide-descendants'
+                }
+                className={slots.startContent()}
+              >
+                <IconColorProvider color={iconColor}>
+                  {textChildren(startContent)}
+                </IconColorProvider>
+              </View>
+            ) : null}
+            {field}
+            {endContent ? (
+              <View
+                onLayout={handleEndLayout}
+                pointerEvents={interactiveContent ? 'box-none' : 'none'}
+                accessibilityElementsHidden={!interactiveContent}
+                importantForAccessibility={
+                  interactiveContent ? 'auto' : 'no-hide-descendants'
+                }
+                className={slots.endContent()}
+              >
+                <IconColorProvider color={iconColor}>
+                  {textChildren(endContent)}
+                </IconColorProvider>
+              </View>
+            ) : null}
+          </View>
+        ) : (
+          field
+        )}
         {errorMessage ? (
           <Text className={slots.error()}>{errorMessage}</Text>
         ) : description ? (

package/src/components/otp-input/index.tsx

@@ -49,7 +49,10 @@ const otpVariants = tv({
     container: 'gap-1.5',
     row: 'flex-row items-center',
     cell: 'items-center justify-center rounded-lg border border-input bg-background',
-    char: 'text-foreground',
+    /* The typed character is drawn by an Animated.Text rather than the Text
+       primitive, so its weight class has to be written here for an app's
+       --font-normal token to reach it. */
+    char: 'font-normal text-foreground',
     caret: 'w-0.5 rounded-full bg-foreground',
     separator: 'h-0.5 rounded-full bg-border',
     error: 'text-sm text-destructive',

package/src/components/panelside/index.tsx

@@ -740,7 +740,7 @@ function PanelsideSearch({
          * text and the placeholder sit below the middle of the row. A length
          * sets the size alone and leaves the line box the font's own.
          */
-        className={cn('h-full flex-1 text-[16px] text-foreground', className)}
+        className={cn('h-full flex-1 font-normal text-[16px] text-foreground', className)}
         style={typeof textTint === 'string' ? { color: textTint } : undefined}
         accessibilityRole="search"
         returnKeyType="search"