panelui-native 0.36.0 → 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

@@ -27,6 +27,13 @@
  * 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
@@ -155,11 +162,18 @@ export interface InputProps
   /** Content inside the field, after the text — an icon, a unit, a count. */
   endContent?: ReactNode;
   /**
-   * Let touches reach the content instead of falling through to the field.
+   * 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.
    *
-   * Off by default: an icon is decoration, and a tap anywhere on a field
-   * should put the caret in it rather than hitting a dead spot. Turn it on for
-   * content that does something — a clear button, a show-password toggle.
+   * 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;
   /**
@@ -205,7 +219,7 @@ export const Input = forwardRef<TextInput, InputProps>(
       disabled,
       startContent,
       endContent,
-      interactiveContent = false,
+      interactiveContent = true,
       variant,
       size,
       avoidKeyboard = false,
@@ -342,7 +356,7 @@ export const Input = forwardRef<TextInput, InputProps>(
             {startContent ? (
               <View
                 onLayout={handleStartLayout}
-                pointerEvents={interactiveContent ? 'auto' : 'none'}
+                pointerEvents={interactiveContent ? 'box-none' : 'none'}
                 accessibilityElementsHidden={!interactiveContent}
                 importantForAccessibility={
                   interactiveContent ? 'auto' : 'no-hide-descendants'
@@ -358,7 +372,7 @@ export const Input = forwardRef<TextInput, InputProps>(
             {endContent ? (
               <View
                 onLayout={handleEndLayout}
-                pointerEvents={interactiveContent ? 'auto' : 'none'}
+                pointerEvents={interactiveContent ? 'box-none' : 'none'}
                 accessibilityElementsHidden={!interactiveContent}
                 importantForAccessibility={
                   interactiveContent ? 'auto' : 'no-hide-descendants'

package/src/components/select/index.tsx

@@ -26,9 +26,16 @@
  * the option labels. The filter narrows what is *shown* — the declared options
  * are still the source of truth, so nothing has to be lifted into state to make
  * it work.
+ *
+ * A list long enough to need a filter is usually long enough to want dividing,
+ * so options can be wrapped in `Select.Group` under a heading. Grouping is
+ * presentational — the value is still a flat string — and the filter reaches
+ * through it, dropping any group the query empties rather than leaving a
+ * heading standing over nothing.
  */
 import {
   Children,
+  cloneElement,
   createContext,
   isValidElement,
   useCallback,
@@ -36,6 +43,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type ReactElement,
   type ReactNode,
 } from 'react';
 import {
@@ -59,6 +67,7 @@ import { getNativeUI } from '../../native';
 import { Portal } from '../../primitives/portal';
 import { Text, textChildren } from '../../primitives/text';
 import { useBackHandler } from '../../hooks/use-back-handler';
+import { cn } from '../../utils/cn';
 import { BottomSheet } from '../bottom-sheet';
 import { InputGroup } from '../input-group';
 
@@ -74,6 +83,8 @@ const selectVariants = tv({
     item: 'flex-row items-center gap-2 rounded-lg px-3 py-3',
     itemLabel: 'flex-1 text-base font-medium text-foreground',
     itemIndicator: 'h-5 w-5 items-center justify-center',
+    group: 'gap-1',
+    groupLabel: 'px-3 pb-1 pt-2',
   },
   variants: {
     selected: {
@@ -151,6 +162,96 @@ function SelectItem({ value, label, disabled }: SelectItemProps) {
   );
 }
 
+export interface SelectGroupProps {
+  /**
+   * Heading over the run of options. Announced as a header, so a screen reader
+   * reaching the group is told what it is before walking into it.
+   */
+  label?: string;
+  /** Extra classes for the group wrapper. */
+  className?: string;
+  /** Extra classes for the heading. */
+  labelClassName?: string;
+  children: ReactNode;
+}
+
+/**
+ * A titled run of options.
+ *
+ * Purely a way of arranging the list: a grouped Select still reports one flat
+ * string, and `Select.Item` needs to know nothing about being inside one.
+ */
+function SelectGroup({ label, className, labelClassName, children }: SelectGroupProps) {
+  const { group, groupLabel } = selectVariants();
+
+  return (
+    <View className={cn(group(), className)}>
+      {label ? (
+        <View accessibilityRole="header" className={cn(groupLabel(), labelClassName)}>
+          <Text size="xs" weight="medium" muted className="uppercase tracking-wide">
+            {label}
+          </Text>
+        </View>
+      ) : null}
+      {textChildren(children)}
+    </View>
+  );
+}
+
+/**
+ * Walk the declared children, visiting every `Select.Item` — including the ones
+ * nested inside a `Select.Group`.
+ *
+ * Grouping is a rendering concern, but the selected label and the native
+ * picker's option list both want the flat set, so the tree is flattened once
+ * here rather than in each of them.
+ */
+function eachOption(children: ReactNode, visit: (option: SelectItemProps) => void) {
+  Children.forEach(children, (child) => {
+    if (!isValidElement(child)) return;
+    if (child.type === SelectGroup) {
+      eachOption((child.props as SelectGroupProps).children, visit);
+      return;
+    }
+    if (child.type !== SelectItem) return;
+    const { value, label, disabled } = child.props as SelectItemProps;
+    visit({ value, label, disabled });
+  });
+}
+
+/**
+ * The children a query leaves standing.
+ *
+ * A group is rebuilt around whatever survives inside it and dropped when that
+ * is nothing — a heading with no options under it reads as a section that
+ * failed to load rather than one the filter emptied. Anything that is neither
+ * an item nor a group is left alone: a caption or a divider the caller put in
+ * the list is not something a filter has an opinion about.
+ */
+function filterOptions(children: ReactNode, needle: string): ReactNode[] {
+  const kept: ReactNode[] = [];
+
+  Children.forEach(children, (child) => {
+    if (!isValidElement(child)) return;
+
+    if (child.type === SelectGroup) {
+      const props = child.props as SelectGroupProps;
+      const inner = filterOptions(props.children, needle);
+      if (inner.length) {
+        kept.push(cloneElement(child as ReactElement<SelectGroupProps>, {}, inner));
+      }
+      return;
+    }
+
+    if (child.type === SelectItem) {
+      const { label } = child.props as SelectItemProps;
+      if (label.toLowerCase().includes(needle)) kept.push(child);
+    }
+  });
+
+  return kept;
+}
+
 /** Trigger frame in window coordinates, measured when the list opens. */
 interface Anchor {
   x: number;
@@ -242,15 +343,7 @@ function SelectRoot({
 
   const options = useMemo(() => {
     const collected: SelectItemProps[] = [];
-    Children.forEach(children, (child) => {
-      if (isValidElement<SelectItemProps>(child)) {
-        collected.push({
-          value: child.props.value,
-          label: child.props.label,
-          disabled: child.props.disabled,
-        });
-      }
-    });
+    eachOption(children, (option) => collected.push(option));
     return collected;
   }, [children]);
 
@@ -269,11 +362,7 @@ function SelectRoot({
     const needle = searchable ? query.trim().toLowerCase() : '';
     if (!needle) return null;
 
-    return Children.toArray(children).filter(
-      (child) =>
-        isValidElement<SelectItemProps>(child) &&
-        child.props.label.toLowerCase().includes(needle)
-    );
+    return filterOptions(children, needle);
   }, [children, query, searchable]);
 
   const close = useCallback(() => {
@@ -360,7 +449,13 @@ function SelectRoot({
   const trigger = (
     <Pressable
       ref={triggerRef}
-      accessibilityRole="button"
+      /*
+       * A trigger that owns a list of options and reports whether that list is
+       * open is a combobox, not a button — and `expanded` only means anything
+       * on a role that can be expanded. Announced as "collapsed"/"expanded"
+       * rather than as a button whose state has nowhere to be read.
+       */
+      accessibilityRole="combobox"
       accessibilityState={{ disabled: !!disabled, expanded: open }}
       disabled={disabled}
       onPress={toggle}
@@ -566,6 +661,10 @@ function SelectRoot({
   );
 }
 
+SelectItem.displayName = 'Select.Item';
+SelectGroup.displayName = 'Select.Group';
+
 export const Select = Object.assign(SelectRoot, {
   Item: SelectItem,
+  Group: SelectGroup,
 });

package/src/index.ts

@@ -235,6 +235,7 @@ export {
   Select,
   type SelectProps,
   type SelectItemProps,
+  type SelectGroupProps,
   type SelectPresentation,
 } from './components/select';
 export {
@@ -304,6 +305,15 @@ export {
   type ChipVariant,
   type ChipSize,
 } from './components/chip';
+export {
+  Combobox,
+  type ComboboxProps,
+  type ComboboxItemProps,
+  type ComboboxGroupProps,
+  type ComboboxMode,
+  type ComboboxSelection,
+  type ComboboxPresentation,
+} from './components/combobox';
 export {
   Drawer,
   type DrawerProps,