panelui-native 0.36.0 → 0.40.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/heatmap-chart/index.tsx

@@ -11,6 +11,7 @@
  *
  * ```tsx
  * <HeatmapChart data={weeks}>
+ *   <HeatmapChart.Header title="Contributions" value="1,204" legend />
  *   <HeatmapChart.YAxis />
  *   <HeatmapChart.XAxis />
  *   <HeatmapChart.Cells />
@@ -132,7 +133,7 @@ const MONTHS = [
  * composition stays a flat list of children instead of four nested slots the
  * caller has to remember the order of.
  */
-type Slot = 'cells' | 'x-axis' | 'y-axis' | 'rules' | 'tooltip' | 'legend';
+type Slot = 'cells' | 'x-axis' | 'y-axis' | 'rules' | 'tooltip' | 'legend' | 'header';
 
 export type HeatmapLayout = 'fluid' | 'fill';
 
@@ -566,6 +567,10 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
         onLayout={onLayout}
         className={cn('w-full', className)}
       >
+        {/* Above the axis gutter as well as the grid: the header is about the
+            whole chart, so it starts at the chart's edge, not the grid's. */}
+        {parts.header}
+
         {parts.x ? (
           <View style={{ paddingLeft: axisWidth }}>{parts.x}</View>
         ) : null}
@@ -605,6 +610,7 @@ interface Parts {
   y: React.ReactElement<{ width?: number }> | null;
   tooltip: ReactNode[];
   legend: ReactNode[];
+  header: ReactNode[];
   columns: number;
 }
 
@@ -617,6 +623,7 @@ function splitParts(children: ReactNode): Parts {
     y: null,
     tooltip: [],
     legend: [],
+    header: [],
     columns: 0,
   };
 
@@ -630,6 +637,7 @@ function splitParts(children: ReactNode): Parts {
     else if (slot === 'rules') parts.rules.push(keyed);
     else if (slot === 'tooltip') parts.tooltip.push(keyed);
     else if (slot === 'legend') parts.legend.push(keyed);
+    else if (slot === 'header') parts.header.push(keyed);
     else parts.cells.push(keyed);
   });
 
@@ -753,6 +761,12 @@ export interface HeatmapXAxisProps {
    * derived. Return an empty string to leave the column unlabelled.
    */
   formatLabel?: (date: Date, column: number) => string;
+  /**
+   * Column labels, left to right. Overrides the month names — for a grid whose
+   * columns are not weeks, where there is no month to change and so nothing to
+   * emit a label on.
+   */
+  labels?: string[];
 }
 
 /**
@@ -760,13 +774,21 @@ export interface HeatmapXAxisProps {
  *
  * A label is emitted where the month changes rather than at a fixed interval,
  * because months are not the same length — spacing them evenly puts "Mar" over
- * a week in February.
+ * a week in February. A grid whose columns are not weeks has no such signal, so
+ * it passes `labels` and gets one over every column.
  */
-function HeatmapXAxis({ className, formatLabel }: HeatmapXAxisProps) {
+function HeatmapXAxis({ className, formatLabel, labels: given }: HeatmapXAxisProps) {
   const { data, grid } = useHeatmap('HeatmapChart.XAxis');
   const step = grid.size + grid.gap;
 
   const labels = useMemo(() => {
+    if (given) {
+      return given
+        .slice(0, data.length)
+        .map((label, column) => ({ column, label }))
+        .filter((entry) => entry.label);
+    }
+
     const out: { column: number; label: string }[] = [];
     let lastMonth = -1;
 
@@ -784,7 +806,7 @@ function HeatmapXAxis({ className, formatLabel }: HeatmapXAxisProps) {
     // collides with the next one. Drop it when it has no room.
     if (out.length > 1 && out[1]!.column - out[0]!.column < 3) out.shift();
     return out;
-  }, [data, formatLabel]);
+  }, [data, formatLabel, given]);
 
   return (
     <View className={cn('h-4', className)} style={{ width: grid.width }}>
@@ -1002,9 +1024,16 @@ function HeatmapTooltip({
 }
 HeatmapTooltip.slot = 'tooltip' as Slot;
 
+/*
+ * A cell with no date is not a cell with no data — it is a cell in a grid that
+ * is not a calendar, and it has a count like any other. Saying "No data" over
+ * it reports a hole in the data that is not there. Without a date there is
+ * simply nothing to say after the number, so the number is the whole label,
+ * and a grid that wants a noun for it passes `formatLabel`.
+ */
 function defaultTooltipLabel(cell: HeatmapCell) {
+  if (!cell.date) return `${cell.count}`;
   const count = `${cell.count} ${cell.count === 1 ? 'contribution' : 'contributions'}`;
-  if (!cell.date) return 'No data';
   const date = `${MONTHS[cell.date.getMonth()]} ${cell.date.getDate()}`;
   return `${count} on ${date}`;
 }
@@ -1061,7 +1090,120 @@ function HeatmapLegend({
 }
 HeatmapLegend.slot = 'legend' as Slot;
 
+/* -------------------------------------------------------------------------- */
+/* Header                                                                     */
+/* -------------------------------------------------------------------------- */
+
+export interface HeatmapHeaderProps extends ViewProps {
+  className?: string;
+  /** Small line above the value — what the grid is of. */
+  title?: string;
+  /** The readout. The largest thing on the card, and the first thing read. */
+  value?: string;
+  /** One muted line under the value — a period, a total, the held cell. */
+  caption?: string;
+  /**
+   * Draw the ramp along the trailing edge, `Less ▢▢▢▢▢ More`. The key for a
+   * grid that scrolls sideways, where `HeatmapChart.Legend` under the cells
+   * would scroll away with them.
+   */
+  legend?: boolean;
+  /** Text at the low end of the ramp, when `legend` is set. */
+  lessLabel?: string;
+  /** Text at the high end. */
+  moreLabel?: string;
+  /** Trailing slot — a control, a badge, a range picker. Wins over `legend`. */
+  children?: ReactNode;
+}
+
+/**
+ * The strip above the grid: what the chart is of, what it currently reads, and
+ * what the shading means.
+ *
+ * It belongs to the chart rather than to the card around it because it is about
+ * the *grid* — the number changes as a finger moves across the cells, and the
+ * ramp is the scale the chart itself derived. The card's header is a caption on
+ * the tray the chart sits in; this is the chart introducing itself.
+ *
+ * The value is not derived here. Take it from `onActiveCellChange` and pass the
+ * formatted string down, so one header can show a total when nothing is held
+ * and a day's own count when something is.
+ */
+function HeatmapHeader({
+  className,
+  title,
+  value,
+  caption,
+  legend = false,
+  lessLabel = 'Less',
+  moreLabel = 'More',
+  children,
+  ...props
+}: HeatmapHeaderProps) {
+  const { ramp, opacities, grid, cornerRadius } = useHeatmap('HeatmapChart.Header');
+  // Small enough to sit on one line beside the text, whatever the cells are.
+  const size = Math.max(Math.min(grid.size, 12), 8);
+
+  const trailing =
+    children ??
+    (legend ? (
+      <View className="flex-row items-center gap-1.5">
+        <Text size="xs" muted>
+          {lessLabel}
+        </Text>
+        {ramp.map((fill, level) => (
+          <Svg key={level} width={size} height={size}>
+            <Rect
+              x={0}
+              y={0}
+              width={size}
+              height={size}
+              rx={cornerRadius}
+              ry={cornerRadius}
+              fill={fill}
+              fillOpacity={opacities[level]}
+            />
+          </Svg>
+        ))}
+        <Text size="xs" muted>
+          {moreLabel}
+        </Text>
+      </View>
+    ) : null);
+
+  return (
+    <View
+      {...props}
+      className={cn('flex-row items-start justify-between gap-3 pb-3', className)}
+    >
+      <View className="flex-1 gap-0.5">
+        {title ? (
+          <Text size="xs" muted>
+            {title}
+          </Text>
+        ) : null}
+        {value ? (
+          <Text size="xl" weight="bold">
+            {value}
+          </Text>
+        ) : null}
+        {caption ? (
+          <Text size="xs" muted>
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+      {/* Shrinkable, unlike a view's default in React Native — held rigid, the
+          ramp takes the width it wants and the caption wraps around it. */}
+      {trailing ? <View className="shrink pt-1">{trailing}</View> : null}
+    </View>
+  );
+}
+HeatmapHeader.displayName = 'HeatmapChart.Header';
+HeatmapHeader.slot = 'header' as Slot;
+
 export const HeatmapChart = Object.assign(HeatmapChartRoot, {
+  Header: HeatmapHeader,
   Cells: HeatmapCells,
   Separator: HeatmapSeparator,
   XAxis: HeatmapXAxis,

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'