@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/ColorPicker/parts.tsx

@@ -1,7 +1,12 @@
 import { Palette, X } from "@tamagui/lucide-icons-2";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { ComponentProps, ReactNode, RefObject } from "react";
+import type {
+  ComponentProps,
+  KeyboardEvent as ReactKeyboardEvent,
+  ReactNode,
+  RefObject,
+} from "react";
 import { View, XStack, isWeb } from "tamagui";
 
 import { Button } from "../../Button";
@@ -9,6 +14,8 @@ import { FloatingPanel } from "../../FloatingPanel";
 import { Input as InputParts } from "../../InputParts";
 import { formControlColors } from "../../shared/colorRamps";
 import { useIsInTableCell } from "../../shared/tableCellContext";
+import { t } from "../../shared/t";
+import { AlphaBackground, HueBackground, SaturationBackground } from "./gradients";
 
 // ---------------------------------------------------------------------------
 // Color conversion utilities
@@ -145,6 +152,32 @@ export function normalizeHex(hex: string): string {
 // Styled sub-components
 // ---------------------------------------------------------------------------
 
+// ---------------------------------------------------------------------------
+// Pointer geometry — web getBoundingClientRect / native measureInWindow
+// ---------------------------------------------------------------------------
+
+type Measurable = {
+  getBoundingClientRect?: () => DOMRect;
+  measureInWindow?: (cb: (x: number, y: number, width: number, height: number) => void) => void;
+};
+
+function readPointerGeometry(
+  node: Measurable | null,
+  clientX: number,
+  clientY: number,
+  apply: (x: number, y: number, width: number, height: number) => void,
+) {
+  if (!node) return;
+  if (typeof node.getBoundingClientRect === "function") {
+    const rect = node.getBoundingClientRect();
+    apply(clientX - rect.left, clientY - rect.top, rect.width, rect.height);
+    return;
+  }
+  node.measureInWindow?.((left, top, width, height) => {
+    apply(clientX - left, clientY - top, width, height);
+  });
+}
+
 // ---------------------------------------------------------------------------
 // useDrag — shared pointer-drag state for sliders and panels
 // ---------------------------------------------------------------------------
@@ -175,7 +208,24 @@ function useDrag(onUpdate: (clientX: number, clientY: number) => void) {
     [onUpdate],
   );
 
-  return { onPointerDown };
+  // Native: track move/up on the target (no document listeners).
+  const onPointerMove = useCallback(
+    (e: { clientX: number; clientY: number }) => {
+      if (!isDragging || isWeb) return;
+      onUpdate(e.clientX, e.clientY);
+    },
+    [isDragging, onUpdate],
+  );
+
+  const onPointerUp = useCallback(() => {
+    if (isWeb) return;
+    setIsDragging(false);
+  }, []);
+
+  return {
+    onPointerDown,
+    ...(isWeb ? {} : { onPointerMove, onPointerUp }),
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -197,22 +247,55 @@ export function SaturationPanel({
   onChangeSV,
   size = 220,
 }: SaturationPanelProps) {
-  const panelRef = useRef<HTMLDivElement>(null);
+  const panelRef = useRef<Measurable | null>(null);
 
   const updateColor = useCallback(
     (clientX: number, clientY: number) => {
-      const panel = panelRef.current;
-      if (!panel) return;
-      const rect = panel.getBoundingClientRect();
-      const x = Math.max(0, Math.min(clientX - rect.left, rect.width));
-      const y = Math.max(0, Math.min(clientY - rect.top, rect.height));
-      onChangeSV(Math.round((x / rect.width) * 100), Math.round(100 - (y / rect.height) * 100));
+      readPointerGeometry(panelRef.current, clientX, clientY, (x, y, width, height) => {
+        if (width <= 0 || height <= 0) return;
+        const clampedX = Math.max(0, Math.min(x, width));
+        const clampedY = Math.max(0, Math.min(y, height));
+        onChangeSV(
+          Math.round((clampedX / width) * 100),
+          Math.round(100 - (clampedY / height) * 100),
+        );
+      });
     },
     [onChangeSV],
   );
 
-  const { onPointerDown } = useDrag(updateColor);
-  const hueColor = `hsl(${hue}, 100%, 50%)`;
+  const dragProps = useDrag(updateColor);
+  // expo-linear-gradient needs a concrete color (hsl() is unreliable on native)
+  const hueColor = hsvToHex(hue, 100, 100);
+  const thumbLeft = (saturation / 100) * size - 7;
+  const thumbTop = ((100 - value) / 100) * size - 7;
+
+  const handleKeyDown = useCallback(
+    (e: ReactKeyboardEvent) => {
+      const step = e.shiftKey ? 10 : 1;
+      let s = saturation;
+      let v = value;
+      switch (e.key) {
+        case "ArrowRight":
+          s = Math.min(100, s + step);
+          break;
+        case "ArrowLeft":
+          s = Math.max(0, s - step);
+          break;
+        case "ArrowUp":
+          v = Math.min(100, v + step);
+          break;
+        case "ArrowDown":
+          v = Math.max(0, v - step);
+          break;
+        default:
+          return;
+      }
+      e.preventDefault();
+      onChangeSV(s, v);
+    },
+    [onChangeSV, saturation, value],
+  );
 
   return (
     <View
@@ -223,13 +306,22 @@ export function SaturationPanel({
       overflow="hidden"
       cursor="crosshair"
       position="relative"
-      onPointerDown={onPointerDown}
       userSelect="none"
-      style={{
-        background: `linear-gradient(to top, #000, transparent), linear-gradient(to right, #fff, ${hueColor})`,
-        touchAction: "none",
-      }}
+      tabIndex={0}
+      role="slider"
+      aria-label={t("Saturation and brightness")}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={value}
+      aria-valuetext={t("Saturation {{saturation}}%, brightness {{brightness}}%", {
+        saturation,
+        brightness: value,
+      })}
+      {...dragProps}
+      {...(isWeb && { onKeyDown: handleKeyDown })}
+      style={isWeb ? { touchAction: "none" } : undefined}
     >
+      <SaturationBackground hueColor={hueColor} width={size} height={size} />
       <View
         position="absolute"
         width={14}
@@ -237,13 +329,13 @@ export function SaturationPanel({
         borderRadius={7}
         borderWidth={2}
         borderColor="white"
-        style={{
-          left: `${saturation}%`,
-          top: `${100 - value}%`,
-          transform: "translate(-50%, -50%)",
-          boxShadow: "0 0 2px rgba(0,0,0,0.6)",
-          pointerEvents: "none",
-        }}
+        left={thumbLeft}
+        top={thumbTop}
+        pointerEvents="none"
+        zIndex={1}
+        {...(isWeb
+          ? { style: { boxShadow: "0 0 2px rgba(0,0,0,0.6)" } }
+          : { shadowColor: "#000", shadowOpacity: 0.6, shadowRadius: 2 })}
       />
     </View>
   );
@@ -260,20 +352,49 @@ interface HueStripProps {
 }
 
 export function HueStrip({ hue, onChangeHue, width = 220 }: HueStripProps) {
-  const stripRef = useRef<HTMLDivElement>(null);
+  const stripRef = useRef<Measurable | null>(null);
 
   const updateHue = useCallback(
-    (clientX: number, _clientY: number) => {
-      const strip = stripRef.current;
-      if (!strip) return;
-      const rect = strip.getBoundingClientRect();
-      const x = Math.max(0, Math.min(clientX - rect.left, rect.width));
-      onChangeHue(Math.round((x / rect.width) * 360));
+    (clientX: number, clientY: number) => {
+      readPointerGeometry(stripRef.current, clientX, clientY, (x, _y, w) => {
+        if (w <= 0) return;
+        const clampedX = Math.max(0, Math.min(x, w));
+        onChangeHue(Math.round((clampedX / w) * 360));
+      });
     },
     [onChangeHue],
   );
 
-  const { onPointerDown } = useDrag(updateHue);
+  const dragProps = useDrag(updateHue);
+  const thumbLeft = (hue / 360) * width - 3;
+
+  const handleKeyDown = useCallback(
+    (e: ReactKeyboardEvent) => {
+      const step = e.shiftKey ? 10 : 1;
+      let next = hue;
+      switch (e.key) {
+        case "ArrowRight":
+        case "ArrowUp":
+          next = Math.min(360, hue + step);
+          break;
+        case "ArrowLeft":
+        case "ArrowDown":
+          next = Math.max(0, hue - step);
+          break;
+        case "Home":
+          next = 0;
+          break;
+        case "End":
+          next = 360;
+          break;
+        default:
+          return;
+      }
+      e.preventDefault();
+      onChangeHue(next);
+    },
+    [hue, onChangeHue],
+  );
 
   return (
     <View
@@ -283,14 +404,18 @@ export function HueStrip({ hue, onChangeHue, width = 220 }: HueStripProps) {
       borderRadius="$2"
       cursor="pointer"
       position="relative"
-      onPointerDown={onPointerDown}
       userSelect="none"
-      style={{
-        background:
-          "linear-gradient(to right, #f00 0%, #ff0 17%, #0f0 33%, #0ff 50%, #00f 67%, #f0f 83%, #f00 100%)",
-        touchAction: "none",
-      }}
+      tabIndex={0}
+      role="slider"
+      aria-label={t("Hue")}
+      aria-valuemin={0}
+      aria-valuemax={360}
+      aria-valuenow={hue}
+      {...dragProps}
+      {...(isWeb && { onKeyDown: handleKeyDown })}
+      style={isWeb ? { touchAction: "none" } : undefined}
     >
+      <HueBackground width={width} height={14} />
       <View
         position="absolute"
         width={6}
@@ -299,12 +424,12 @@ export function HueStrip({ hue, onChangeHue, width = 220 }: HueStripProps) {
         borderWidth={2}
         borderColor="white"
         top={-2}
-        style={{
-          left: `${(hue / 360) * 100}%`,
-          transform: "translateX(-50%)",
-          boxShadow: "0 0 2px rgba(0,0,0,0.6)",
-          pointerEvents: "none",
-        }}
+        left={thumbLeft}
+        pointerEvents="none"
+        zIndex={1}
+        {...(isWeb
+          ? { style: { boxShadow: "0 0 2px rgba(0,0,0,0.6)" } }
+          : { shadowColor: "#000", shadowOpacity: 0.6, shadowRadius: 2 })}
       />
     </View>
   );
@@ -331,21 +456,50 @@ export function AlphaStrip({
   onChangeAlpha,
   width = 220,
 }: AlphaStripProps) {
-  const stripRef = useRef<HTMLDivElement>(null);
+  const stripRef = useRef<Measurable | null>(null);
   const hex = useMemo(() => hsvToHex(hue, saturation, value), [hue, saturation, value]);
 
   const updateAlpha = useCallback(
-    (clientX: number, _clientY: number) => {
-      const strip = stripRef.current;
-      if (!strip) return;
-      const rect = strip.getBoundingClientRect();
-      const x = Math.max(0, Math.min(clientX - rect.left, rect.width));
-      onChangeAlpha(Math.round((x / rect.width) * 100));
+    (clientX: number, clientY: number) => {
+      readPointerGeometry(stripRef.current, clientX, clientY, (x, _y, w) => {
+        if (w <= 0) return;
+        const clampedX = Math.max(0, Math.min(x, w));
+        onChangeAlpha(Math.round((clampedX / w) * 100));
+      });
     },
     [onChangeAlpha],
   );
 
-  const { onPointerDown } = useDrag(updateAlpha);
+  const dragProps = useDrag(updateAlpha);
+  const thumbLeft = (alpha / 100) * width - 3;
+
+  const handleKeyDown = useCallback(
+    (e: ReactKeyboardEvent) => {
+      const step = e.shiftKey ? 10 : 1;
+      let next = alpha;
+      switch (e.key) {
+        case "ArrowRight":
+        case "ArrowUp":
+          next = Math.min(100, alpha + step);
+          break;
+        case "ArrowLeft":
+        case "ArrowDown":
+          next = Math.max(0, alpha - step);
+          break;
+        case "Home":
+          next = 0;
+          break;
+        case "End":
+          next = 100;
+          break;
+        default:
+          return;
+      }
+      e.preventDefault();
+      onChangeAlpha(next);
+    },
+    [alpha, onChangeAlpha],
+  );
 
   return (
     <View
@@ -356,38 +510,18 @@ export function AlphaStrip({
       cursor="pointer"
       position="relative"
       overflow="hidden"
-      onPointerDown={onPointerDown}
       userSelect="none"
-      style={{
-        touchAction: "none",
-      }}
+      tabIndex={0}
+      role="slider"
+      aria-label={t("Opacity")}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={alpha}
+      {...dragProps}
+      {...(isWeb && { onKeyDown: handleKeyDown })}
+      style={isWeb ? { touchAction: "none" } : undefined}
     >
-      {/* Checkerboard background */}
-      <View
-        position="absolute"
-        top={0}
-        left={0}
-        right={0}
-        bottom={0}
-        style={{
-          backgroundImage:
-            "linear-gradient(45deg, #ccc 25%, transparent 25%), linear-gradient(135deg, #ccc 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #ccc 75%), linear-gradient(135deg, transparent 75%, #ccc 75%)",
-          backgroundSize: "8px 8px",
-          backgroundPosition: "0 0, 4px 0, 4px -4px, 0px 4px",
-        }}
-      />
-      {/* Alpha gradient */}
-      <View
-        position="absolute"
-        top={0}
-        left={0}
-        right={0}
-        bottom={0}
-        style={{
-          background: `linear-gradient(to right, transparent, ${hex})`,
-        }}
-      />
-      {/* Thumb */}
+      <AlphaBackground hex={hex} width={width} height={14} />
       <View
         position="absolute"
         width={6}
@@ -396,12 +530,12 @@ export function AlphaStrip({
         borderWidth={2}
         borderColor="white"
         top={-2}
-        style={{
-          left: `${alpha}%`,
-          transform: "translateX(-50%)",
-          boxShadow: "0 0 2px rgba(0,0,0,0.6)",
-          pointerEvents: "none",
-        }}
+        left={thumbLeft}
+        pointerEvents="none"
+        zIndex={1}
+        {...(isWeb
+          ? { style: { boxShadow: "0 0 2px rgba(0,0,0,0.6)" } }
+          : { shadowColor: "#000", shadowOpacity: 0.6, shadowRadius: 2 })}
       />
     </View>
   );
@@ -411,10 +545,17 @@ export function AlphaStrip({
 // PresetSwatches — grid of clickable preset colors
 // ---------------------------------------------------------------------------
 
-interface PresetSwatchesProps {
-  presetColors: string[];
-  selectedColor: string;
-  onSelect: (color: string) => void;
+export interface PresetSwatchEntry {
+  /** Accessible name for the swatch */
+  name?: string;
+  /** Hex color value, or null for a "no color" swatch */
+  value: string | null;
+}
+
+export interface PresetSwatchesProps {
+  presetColors: (string | PresetSwatchEntry)[];
+  selectedColor: string | null;
+  onSelect: (color: string | null) => void;
   width?: number;
 }
 
@@ -429,23 +570,39 @@ export function PresetSwatches({
   const swatchSize = width && width < 200 ? 18 : 22;
   return (
     <XStack flexWrap="wrap" gap="$1.5" width={width} justifyContent="center">
-      {presetColors.map((color) => {
-        const isSelected = selectedColor.toUpperCase() === color.toUpperCase();
+      {presetColors.map((preset) => {
+        const entry = typeof preset === "string" ? { value: preset } : preset;
+        const isSelected =
+          entry.value === null
+            ? selectedColor === null
+            : (selectedColor ?? "").toUpperCase() === entry.value.toUpperCase();
         return (
           <Button
-            key={color}
+            key={entry.name ?? entry.value ?? "none"}
             size="$2"
             width={swatchSize}
             height={swatchSize}
             padding={0}
-            backgroundColor={color}
-            borderWidth={0}
+            backgroundColor={entry.value ?? formControlColors.background}
+            borderWidth={1}
+            borderColor={formControlColors.border}
             borderRadius={knobProps.borderRadius.borderRadius}
-            onPress={() => onSelect(color)}
+            onPress={() => onSelect(entry.value)}
             opacity={isSelected ? 1 : 0.75}
             scale={isSelected ? 1.15 : 1}
             hoverStyle={{ opacity: 1, scale: 1.1 }}
-          />
+            aria-label={entry.name ?? (entry.value ? `Color ${entry.value}` : "Remove color")}
+          >
+            {entry.value === null && (
+              <View
+                position="absolute"
+                width={swatchSize - 6}
+                height={2}
+                backgroundColor="$red10"
+                transform={[{ rotate: "45deg" }]}
+              />
+            )}
+          </Button>
         );
       })}
     </XStack>
@@ -463,6 +620,10 @@ interface ColorPickerInputTriggerProps {
   onReset: () => void;
   onButtonPress: () => void;
   error?: boolean;
+  id?: string;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+  "aria-describedby"?: string;
   "aria-required"?: boolean;
   "aria-invalid"?: boolean;
   inputProps?: Omit<
@@ -475,12 +636,26 @@ export const ColorPickerInputTrigger = InputParts.Area.styleable<ColorPickerInpu
   (props, ref) => {
     const { knobProps } = useResolvedKnobs();
     const inTableCell = useIsInTableCell();
-    const { value, onButtonPress, onReset, disabled, placeholder, error } = props;
+    const {
+      value,
+      onButtonPress,
+      onReset,
+      disabled,
+      placeholder,
+      error,
+      id,
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
+      "aria-describedby": ariaDescribedBy,
+      "aria-required": ariaRequired,
+      "aria-invalid": ariaInvalid,
+    } = props;
     return (
       <View ref={ref}>
         <InputParts
           cursor="pointer"
-          onPress={disabled ? undefined : onButtonPress}
+          // Native: FloatingPanel owns open — a second onPress double-toggles closed.
+          onPress={isWeb && !disabled ? onButtonPress : undefined}
           size={knobProps.sizeToken}
         >
           <InputParts.Box
@@ -493,20 +668,28 @@ export const ColorPickerInputTrigger = InputParts.Area.styleable<ColorPickerInpu
                 height={20}
                 borderRadius={knobProps.borderRadius.borderRadius}
                 backgroundColor={value || formControlColors.background}
-                aria-label="Color swatch"
+                aria-label={t("Color swatch")}
               />
             </InputParts.Icon>
             {!inTableCell && (
               <InputParts.Area
                 readOnly
+                id={id}
                 value={value}
                 placeholder={placeholder}
                 pointerEvents="none"
                 disabled={disabled}
+                aria-label={ariaLabel}
+                aria-labelledby={ariaLabelledBy}
+                aria-describedby={ariaDescribedBy}
+                aria-required={ariaRequired}
+                aria-invalid={ariaInvalid}
               />
             )}
             <InputParts.Button
+              aria-label={value ? t("Clear color") : t("Pick color")}
               onPress={(e) => {
+                if (disabled) return;
                 if (value) {
                   e.stopPropagation();
                   onReset();
@@ -533,7 +716,10 @@ interface ColorPickerPopoverShellProps {
   onOpenChange: (open: boolean) => void;
   trigger: ReactNode;
   children: ReactNode;
+  disabled?: boolean;
   popoverRef?: RefObject<any>;
+  /** Native trigger announcement (name / current value / hint) — see FloatingPanel. */
+  triggerA11y?: { label?: string; value?: string; hint?: string };
 }
 
 export function ColorPickerPopoverShell({
@@ -541,15 +727,19 @@ export function ColorPickerPopoverShell({
   onOpenChange,
   trigger,
   children,
+  disabled,
+  triggerA11y,
 }: ColorPickerPopoverShellProps) {
   return (
     <FloatingPanel
       open={open}
       onOpenChange={onOpenChange}
       trigger={trigger}
+      disabled={disabled}
       scrollable
       sizing="fill"
       fitContent
+      triggerA11y={triggerA11y}
     >
       {children}
     </FloatingPanel>

package/src/fields/Combobox/Combobox.spec.tsx

@@ -1,4 +1,5 @@
-import { describe, expect, it } from "vitest";
+import { act, fireEvent } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Form } from "../../Form";
 import { Combobox } from "./index";
@@ -53,6 +54,33 @@ describe("Combobox", () => {
       );
       expect(result.findTextElement("Disabled")).toBeDefined();
     });
+
+    it("fires canonical onChange and the deprecated onValueChange alias once when dismissing a chip", async () => {
+      const onChange = vi.fn();
+      const onValueChange = vi.fn();
+      const result = renderWithProviders(
+        <Combobox
+          label="Fruits"
+          name="fruits"
+          options={options}
+          multiple
+          dismissible
+          value={["apple", "banana"]}
+          onChange={onChange}
+          onValueChange={onValueChange}
+        />,
+      );
+      const dismiss = result.container.querySelector('[aria-label="Remove"]');
+      expect(dismiss).toBeTruthy();
+      await act(async () => {
+        if (dismiss) fireEvent.click(dismiss);
+      });
+      // Exactly once each — guards against the standalone double-fire bug.
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith(["banana"]);
+      expect(onValueChange).toHaveBeenCalledTimes(1);
+      expect(onValueChange).toHaveBeenCalledWith(["banana"]);
+    });
   });
 
   describe("with form context", () => {
@@ -65,4 +93,64 @@ describe("Combobox", () => {
       expect(result.findTextElement("Fruit")).toBeDefined();
     });
   });
+
+  describe("async contract additions (valueLabel / clearable / searchError / description)", () => {
+    it("shows valueLabel in the trigger when the value is not in options", () => {
+      const result = renderWithProviders(
+        <Combobox label="User" options={[]} value="user-001" valueLabel="Jane Doe" />,
+      );
+      expect(result.findTextElement("Jane Doe")).toBeDefined();
+    });
+
+    it("still shows the placeholder for an unknown value without valueLabel", () => {
+      const result = renderWithProviders(
+        <Combobox label="User" options={[]} value="user-001" placeholder="Pick user" />,
+      );
+      expect(result.findTextElement("Pick user")).toBeDefined();
+    });
+
+    it("readOnly renders valueLabel for a value missing from options", () => {
+      const result = renderWithProviders(
+        <Combobox label="User" options={[]} value="user-001" valueLabel="Jane Doe" readOnly />,
+      );
+      expect(result.findTextElement("Jane Doe")).toBeDefined();
+    });
+
+    it("clearable trigger clears the value through canonical onChange", async () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Combobox label="Fruit" options={options} value="apple" clearable onChange={onChange} />,
+      );
+      const clear = result.container.querySelector('[aria-label="Clear"]');
+      expect(clear).toBeTruthy();
+      await act(async () => {
+        if (clear) fireEvent.click(clear);
+      });
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith("");
+    });
+
+    it("renders option descriptions in the open dropdown", async () => {
+      const withDescriptions = [{ value: "u1", label: "user1@x.com", description: "User One" }];
+      const result = renderWithProviders(
+        <Combobox label="User" options={withDescriptions} open onSearch={() => {}} />,
+      );
+      await act(async () => {});
+      expect(result.findTextElement("User One")).toBeDefined();
+    });
+
+    it("shows searchError instead of the empty state in the open dropdown", async () => {
+      const result = renderWithProviders(
+        <Combobox
+          label="User"
+          options={[]}
+          open
+          onSearch={() => {}}
+          searchError="You don't have permission to search User"
+        />,
+      );
+      await act(async () => {});
+      expect(result.findTextElement("You don't have permission to search User")).toBeDefined();
+    });
+  });
 });