@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/ColorPicker/index.tsx

@@ -2,7 +2,7 @@ import type { DeepKeys, DeepValue } from "@tanstack/form-core";
 import { Pipette } from "@tamagui/lucide-icons-2";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { type ComponentProps, useCallback, useEffect, useRef, useState } from "react";
-import { type Popover, Text, View, XStack, YStack, useProps } from "tamagui";
+import { type Popover, Text, View, XStack, YStack, isWeb, useProps } from "tamagui";
 import { Button } from "../../Button";
 
 import { Field, FieldLayout } from "../../fieldLayout";
@@ -15,6 +15,7 @@ import {
 import type { FormFieldProps } from "../../fieldLayout";
 import { Input as InputParts } from "../../InputParts";
 import { Skeleton } from "../../Skeleton";
+import { t } from "../../shared/t";
 import type { FieldComponentProps, Validator } from "../../types";
 
 import {
@@ -46,7 +47,9 @@ export type ColorPickerProps<
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > = Omit<
   FormFieldProps<TParentData, TName, TFieldValidator, TFormValidator, TData>,
-  "children" | "field"
+  // "onChange": FormFieldProps carries the DOM ChangeEventHandler from
+  // YStackProps; this field exposes a canonical value callback instead.
+  "children" | "field" | "onChange"
 > &
   Partial<
     Omit<
@@ -62,7 +65,12 @@ export type ColorPickerProps<
     inputProps?: Omit<InputProps, "value" | "onChangeText" | "ref">;
     /** Controlled value (for standalone usage without form) */
     value?: string;
-    /** Called when value changes (for standalone usage without form) */
+    /**
+     * Canonical change handler, consistent with the rest of the field family.
+     * Fires in both standalone and form mode. Prefer this over `onValueChange`.
+     */
+    onChange?: (value: string) => void;
+    /** @deprecated Use `onChange` instead. */
     onValueChange?: (value: string) => void;
     /** When true, renders a skeleton placeholder instead of the color picker */
     skeleton?: boolean;
@@ -261,7 +269,7 @@ interface ColorBodyProps {
   onChangeHue: (h: number) => void;
   onChangeSV: (s: number, v: number) => void;
   onChangeAlpha: (a: number) => void;
-  onHexInput: (hex: string) => void;
+  onHexInput: (hex: string, alpha?: number) => void;
   onSelectPreset: (color: string) => void;
 }
 
@@ -288,9 +296,13 @@ function ColorBody({
   const { knobProps } = useResolvedKnobs();
   const panelSize = panelSizeMap[knobProps.size] ?? 220;
   const [hexInputValue, setHexInputValue] = useState(selectedColor);
+  const [hexEditing, setHexEditing] = useState(false);
   useEffect(() => {
+    // Don't rewrite the field while the user is typing — a partial entry like
+    // "#112" would commit as a 3-digit hex and clobber the rest of the input.
+    if (hexEditing) return;
     setHexInputValue(selectedColor);
-  }, [selectedColor]);
+  }, [selectedColor, hexEditing]);
 
   const handleHexChange = useCallback(
     (text: string) => {
@@ -298,6 +310,13 @@ function ColorBody({
       const normalized = text.startsWith("#") ? text : `#${text}`;
       if (isValidHex(normalized)) {
         onHexInput(normalizeHex(normalized));
+        return;
+      }
+      // 8-digit hex (#RRGGBBAA): commit the color and apply the alpha channel.
+      const hexWithAlpha = /^#([0-9a-f]{6})([0-9a-f]{2})$/i.exec(normalized);
+      if (hexWithAlpha) {
+        const alphaPercent = Math.round((Number.parseInt(hexWithAlpha[2], 16) / 255) * 100);
+        onHexInput(normalizeHex(`#${hexWithAlpha[1]}`), alphaPercent);
       }
     },
     [onHexInput],
@@ -348,7 +367,9 @@ function ColorBody({
       <PresetSwatches
         presetColors={presetColors}
         selectedColor={selectedColor}
-        onSelect={onSelectPreset}
+        onSelect={(color) => {
+          if (color !== null) onSelectPreset(color);
+        }}
         width={panelSize}
       />
 
@@ -365,8 +386,10 @@ function ColorBody({
             <InputParts.Area
               value={hexInputValue}
               onChangeText={handleHexChange}
+              onFocus={() => setHexEditing(true)}
+              onBlur={() => setHexEditing(false)}
               placeholder="#000000"
-              maxLength={7}
+              maxLength={9}
             />
           </InputParts.Box>
         </InputParts>
@@ -407,6 +430,11 @@ interface ColorPickerControlProps {
   inputProps?: Omit<InputProps, "value" | "onChangeText" | "ref">;
   hasError: boolean;
   required?: boolean;
+  id?: string;
+  hasLabel?: boolean;
+  /** Field label as plain text, for the native trigger announcement. */
+  a11yLabel?: string;
+  helperText?: string;
   onValueChange: (value: string) => void;
   onBlurControl?: () => void;
 }
@@ -422,6 +450,10 @@ function ColorPickerControl({
   inputProps,
   hasError,
   required,
+  id,
+  hasLabel,
+  a11yLabel,
+  helperText,
   onValueChange,
   onBlurControl,
 }: ColorPickerControlProps) {
@@ -433,6 +465,23 @@ function ColorPickerControl({
   const [hsv, setHsv] = useState(() => hexToHsv(initialColor || "#000000"));
   const [alpha, setAlpha] = useState(parsedInitial.alpha);
   const popoverRef = useRef<Popover>(null);
+  const triggerRef = useRef<HTMLElement>(null);
+
+  // Return focus to the trigger when the panel closes (Escape / outside click),
+  // so keyboard users are not dropped back to the top of the document.
+  const restoreTriggerFocus = useCallback(() => {
+    if (!isWeb || typeof document === "undefined") return;
+    requestAnimationFrame(() => {
+      const active = document.activeElement;
+      // Focus can still be parked on a control inside the closing panel while
+      // it animates out — treat that the same as focus already being lost.
+      const inClosingPanel =
+        active instanceof HTMLElement &&
+        !!active.closest('[data-testid="floating-panel-viewport"]');
+      if (active && active !== document.body && !inClosingPanel) return;
+      triggerRef.current?.querySelector?.("input")?.focus();
+    });
+  }, []);
 
   useEffect(() => {
     const parsed = parseColorValue(value, format);
@@ -447,12 +496,6 @@ function ColorPickerControl({
     }
   }, [value, format]);
 
-  const closePopover = useCallback(() => {
-    setOpen(false);
-    popoverRef.current?.close();
-    onBlurControl?.();
-  }, [onBlurControl]);
-
   const updateFromHsv = useCallback(
     (h: number, s: number, v: number) => {
       const hex = hsvToHex(h, s, v).toUpperCase();
@@ -474,22 +517,26 @@ function ColorPickerControl({
   );
 
   const handleHexInput = useCallback(
-    (hex: string) => {
+    (hex: string, nextAlpha?: number) => {
       const normalized = normalizeHex(hex);
       const newHsv = hexToHsv(normalized);
+      const resolvedAlpha = nextAlpha ?? alpha;
       setHsv(newHsv);
       setSelectedColor(normalized);
-      onValueChange(serializeColorValue(normalized, format, alpha, showAlpha));
+      if (nextAlpha !== undefined) setAlpha(nextAlpha);
+      onValueChange(serializeColorValue(normalized, format, resolvedAlpha, showAlpha));
     },
     [alpha, format, onValueChange, showAlpha],
   );
 
+  // DISMISS-BY-INTENT (LC-19): selecting a swatch is an edit, not a dismissal.
+  // The panel stays open — like the sliders and hex input — and only an
+  // outside click / Escape / explicit done closes it.
   const handleSelectPreset = useCallback(
     (color: string) => {
       handleHexInput(normalizeHex(color));
-      closePopover();
     },
-    [closePopover, handleHexInput],
+    [handleHexInput],
   );
 
   const handleClear = useCallback(() => {
@@ -534,7 +581,7 @@ function ColorPickerControl({
           width={20}
           height={20}
           borderRadius={knobProps.borderRadius.borderRadius}
-          marginLeft="$2"
+          marginInlineStart="$2"
           alignSelf="center"
           backgroundColor={displayValue || "transparent"}
         />
@@ -554,18 +601,44 @@ function ColorPickerControl({
     <ColorPickerPopoverShell
       open={open}
       onOpenChange={(nextOpen) => {
+        if (disabled && nextOpen) return;
         setOpen(nextOpen);
-        if (!nextOpen) onBlurControl?.();
+        if (!nextOpen) {
+          onBlurControl?.();
+          restoreTriggerFocus();
+        }
       }}
+      disabled={disabled}
       popoverRef={popoverRef}
+      // "Color, #EF4444": VO gets the field name + current hex on the native
+      // trigger (mirrors the DatePicker/Select triggerA11y pattern).
+      triggerA11y={{
+        label: a11yLabel || t("Color"),
+        value: value || selectedColor || placeholder,
+        hint: helperText,
+      }}
       trigger={
         <ColorPickerInputTrigger
+          ref={triggerRef as never}
           value={value || selectedColor}
           placeholder={placeholder}
           disabled={disabled}
           onReset={handleClear}
-          onButtonPress={() => setOpen(true)}
+          onButtonPress={() => {
+            if (!disabled) setOpen(true);
+          }}
           error={hasError}
+          id={id}
+          aria-labelledby={hasLabel && id ? `${id}-label` : undefined}
+          aria-label={hasLabel ? undefined : t("Color")}
+          aria-describedby={
+            [
+              helperText && id ? `${id}-description` : undefined,
+              hasError && id ? `${id}-error` : undefined,
+            ]
+              .filter(Boolean)
+              .join(" ") || undefined
+          }
           aria-required={required || undefined}
           aria-invalid={hasError || undefined}
           inputProps={inputProps}
@@ -594,7 +667,7 @@ export function ColorPicker<
     format: _format = "hex",
     showAlpha = false,
     presetColors = defaultPresets,
-    placeholder = "Select color",
+    placeholder = t("Select color"),
     inputProps,
     mode,
     name,
@@ -610,12 +683,23 @@ export function ColorPicker<
     size,
     onBlur,
     value: controlledValue,
+    onChange,
     onValueChange,
     skeleton,
     compact,
     id: idProp,
   } = useProps(props);
 
+  // Canonical `onChange` and the alias `onValueChange` both fire from a
+  // single emit per change (same reconciliation as Switch).
+  const emitValueChange = useCallback(
+    (newValue: string) => {
+      onChange?.(newValue);
+      onValueChange?.(newValue);
+    },
+    [onChange, onValueChange],
+  );
+
   const { resolvedForm, knobProps, id } = useFormField({ form, id: idProp, compact });
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
   const [standaloneValue, setStandaloneValue] = useState<string>(
@@ -633,17 +717,28 @@ export function ColorPicker<
   const handleStandaloneChange = useCallback(
     (newValue: string) => {
       setStandaloneValue(newValue);
-      onValueChange?.(newValue);
+      emitValueChange(newValue);
     },
-    [onValueChange],
+    [emitValueChange],
   );
 
   // Render skeleton placeholder
   if (skeleton) {
+    // Mirror LC-20 SKELETON-MIRRORS-ANATOMY: the control is a shrink-wrapped
+    // sizeToken square (not a stretch-width bar), so the label MUST be a
+    // deterministic px width — never % — or it resolves against a width
+    // computed without the % child and overflows. Radius matches the live
+    // ColorPickerInputTrigger / swatch (`knobProps.borderRadius`).
+    const cellSize = size || knobProps.sizeToken;
     return (
-      <InputParts size={size || knobProps.sizeToken}>
-        {label && <Skeleton variant="text" width="30%" height={14} />}
-        <Skeleton variant="rounded" width={knobProps.sizeToken} height={knobProps.sizeToken} />
+      <InputParts size={cellSize}>
+        {label && <Skeleton variant="text" width={96} height={14} />}
+        <Skeleton
+          variant="rounded"
+          width={cellSize}
+          height={cellSize}
+          borderRadius={knobProps.borderRadius.borderRadius}
+        />
       </InputParts>
     );
   }
@@ -667,6 +762,9 @@ export function ColorPicker<
         size={size}
         knobProps={knobProps}
         onBlur={onBlur}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
       >
         <InputParts size={size || knobProps.sizeToken}>
           <ColorPickerControl
@@ -679,6 +777,10 @@ export function ColorPicker<
             readOnly={readOnly}
             inputProps={inputProps}
             hasError={!!errorProp || !!standaloneFormatError}
+            id={id}
+            hasLabel={Boolean(label)}
+            a11yLabel={typeof label === "string" ? label : undefined}
+            helperText={helperText}
             onValueChange={handleStandaloneChange}
             required={required}
             onBlurControl={() => onBlur?.(undefined as never)}
@@ -717,6 +819,8 @@ export function ColorPicker<
             size={size}
             knobProps={knobProps}
             onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             <InputParts size={size || knobProps.sizeToken}>
               <ColorPickerControl
@@ -729,7 +833,15 @@ export function ColorPicker<
                 readOnly={readOnly}
                 inputProps={inputProps}
                 hasError={!!resolvedError || !!fieldFormatError}
-                onValueChange={(newValue) => field.handleChange(newValue as TData)}
+                id={id}
+                hasLabel={Boolean(label)}
+                a11yLabel={typeof label === "string" ? label : undefined}
+                helperText={helperText}
+                onValueChange={(newValue) => {
+                  field.handleChange(newValue as TData);
+                  // Form mode also notifies user callbacks (family norm).
+                  emitValueChange(newValue);
+                }}
                 required={required}
                 onBlurControl={mergeFieldHandler(field, "handleBlur", onBlur)}
               />