@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/fields/Checkbox/index.tsx

@@ -1,7 +1,7 @@
 import type { RovingFocusGroupProps, RovingFocusItemProps } from "@tamagui/roving-focus";
 import { RovingFocusGroup } from "@tamagui/roving-focus";
 import { CheckIcon as CheckRegular } from "@phosphor-icons/react";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ensureFocusVisibleRing, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { ElementRef, KeyboardEvent, PropsWithChildren } from "react";
 import { forwardRef } from "react";
 import type { CheckedState, YStackProps } from "tamagui";
@@ -12,13 +12,23 @@ import {
   Label,
   View,
   createStyledContext,
+  getVariableValue,
   isWeb,
   styled,
   withStaticProperties,
 } from "tamagui";
-import { formCardColors } from "../../shared/colorRamps";
+import { getSize } from "@tamagui/get-token";
+import {
+  CheckboxCardContent,
+  CheckboxCardDescription,
+  CheckboxCardFrame,
+  CheckboxCardLabel,
+  getCardDescriptionSize,
+  getCheckboxCardLayout,
+} from "./CheckboxCard";
 import { CheckboxFieldFrame } from "./CheckboxFieldFrame";
 import { clampRadiusForControl } from "../../shared/utils";
+import { formControlColors } from "../../shared/colorRamps";
 
 // ─── Checkboxes Compound Component ────────────────────────────────────────────
 
@@ -31,13 +41,20 @@ const CheckboxesContext = createStyledContext<{
 });
 
 const FocusGroup = forwardRef<ElementRef<typeof View>, RovingFocusGroupProps>((props, ref) => {
-  const { knobProps } = useResolvedKnobs();
+  const { knobProps, control } = useResolvedKnobs();
+  // DG-A11Y-01: the roving group container is a focusable tab entry point
+  // that forwards focus to its current item — the ring must therefore be
+  // painted synchronously while focus is WITHIN (CellWrapper focusWithin
+  // pattern), not only on the container's own :focus.
+  const groupRing = ensureFocusVisibleRing({ ...control.focusVisibleKnobProps });
   return (
     <RovingFocusGroup
       gap={knobProps.gap.gap}
       focusable
       outlineOffset={1}
-      focusStyle={{ zIndex: 1 }}
+      focusStyle={{ zIndex: 1, ...groupRing }}
+      focusVisibleStyle={{ zIndex: 1, ...groupRing }}
+      focusWithinStyle={{ ...groupRing }}
       {...props}
       ref={ref}
     />
@@ -57,7 +74,8 @@ const FocusGroupItem = forwardRef<any, RovingFocusItemProps & { value: string }>
       focusable: true,
       outlineOffset: 1,
       flexShrink: 1,
-      focusStyle: { zIndex: 1 },
+      focusStyle: { zIndex: 1, ...ensureFocusVisibleRing() },
+      focusVisibleStyle: { zIndex: 1, ...ensureFocusVisibleRing() },
       ...(isWeb && {
         onKeyDown: (e: KeyboardEvent) => {
           if (e.key === "Enter" || e.code === "Space") {
@@ -106,7 +124,12 @@ const CheckboxesImp = <K extends string>(
 };
 
 const CheckboxesCheckbox = TamaguiCheckbox.styleable((checkboxProps, ref) => {
-  const { checked: _userChecked, onCheckedChange: onCheckedChangeProp, ...props } = checkboxProps;
+  const {
+    checked: _userChecked,
+    onCheckedChange: onCheckedChangeProp,
+    children,
+    ...props
+  } = checkboxProps;
   const { values, onValuesChange } = CheckboxesContext.useStyledContext();
   const { value: focusItemValue } = FocusItemContext.useStyledContext();
   const { knobProps } = useResolvedKnobs();
@@ -116,7 +139,21 @@ const CheckboxesCheckbox = TamaguiCheckbox.styleable((checkboxProps, ref) => {
     cappedRadius === 0
       ? { borderWidth: knobProps.borderRadius.borderWidth, borderRadius: 0 }
       : { borderWidth: knobProps.borderRadius.borderWidth, borderRadius: cappedRadius };
+  // Pressable-vs-glyph split (SP-FIXED / WCAG 2.5.5, same anatomy as
+  // fields/Checkbox + RadioGroup): the role=checkbox frame is a 44px
+  // transparent target; the visible 20px box is the inner glyph.
+  const glyphSize = Math.round(getVariableValue(getSize(knobProps.sizeToken)) * 0.45);
+  // Compound cards often pair the control with free-form text (Paragraph)
+  // instead of an associated Label, leaving the checkbox unnamed. Fall back
+  // to the humanized item value; explicit aria-label/labelledby wins.
+  const hasName =
+    (props as Record<string, unknown>)["aria-label"] ||
+    (props as Record<string, unknown>)["aria-labelledby"];
+  const fallbackName = focusItemValue
+    ? focusItemValue.replace(/[-_]+/g, " ").replace(/^\w/, (c) => c.toUpperCase())
+    : undefined;
   const combinedProps = {
+    ...(!hasName && fallbackName ? { "aria-label": fallbackName } : undefined),
     ...props,
     checked: values[focusItemValue],
     onCheckedChange: (checked: CheckedState) => {
@@ -132,49 +169,57 @@ const CheckboxesCheckbox = TamaguiCheckbox.styleable((checkboxProps, ref) => {
     <CheckboxFieldFrame
       ref={ref}
       value={focusItemValue}
-      {...knobProps.inputSurface}
       size={knobProps.sizeToken}
-      {...resolvedRadius}
-      outlined={knobProps.outlined}
       transition={knobProps.transition}
+      width={44}
+      height={44}
+      minWidth={44}
+      minHeight={44}
+      padding={0}
+      borderWidth={0}
+      backgroundColor="transparent"
+      alignItems="center"
+      justifyContent="center"
+      hoverStyle={{ backgroundColor: "transparent", borderColor: "transparent" }}
+      pressStyle={{ backgroundColor: "transparent", borderColor: "transparent" }}
+      focusStyle={{ backgroundColor: "transparent", borderColor: "transparent" }}
+      focusVisibleStyle={{
+        backgroundColor: "transparent",
+        borderColor: "transparent",
+        ...ensureFocusVisibleRing(),
+      }}
+      activeStyle={{ backgroundColor: "transparent", borderColor: "transparent" }}
       {...combinedProps}
-    />
+    >
+      <View
+        width={glyphSize}
+        height={glyphSize}
+        {...knobProps.inputSurface}
+        {...resolvedRadius}
+        backgroundColor={knobProps.outlined ? "transparent" : formControlColors.background}
+        borderColor={formControlColors.border}
+        alignItems="center"
+        justifyContent="center"
+      >
+        {children}
+      </View>
+    </CheckboxFieldFrame>
   );
 });
 
-const CheckboxCardFrame = styled(View, {
-  cursor: "pointer",
-  width: "100%",
-  padding: "$3",
-  borderRadius: "$4",
-  backgroundColor: formCardColors.background.base,
-  borderColor: formCardColors.border.base,
-  borderWidth: 1,
-  hoverStyle: {
-    borderColor: formCardColors.border.hover,
-  },
-  variants: {
-    active: {
-      true: {
-        backgroundColor: formCardColors.background.active,
-        borderColor: formCardColors.border.active,
-      },
-    },
-  } as const,
-});
-
 const CheckboxCard = CheckboxCardFrame.styleable<{ unstyled?: boolean; active?: boolean }>(
   (cardProps, ref) => {
     const { values } = CheckboxesContext.useStyledContext();
     const { value } = FocusItemContext.useStyledContext();
     const { knobProps } = useResolvedKnobs();
     const selected = values[value];
+    const layout = getCheckboxCardLayout(knobProps.space);
 
     return (
       <CheckboxCardFrame
         ref={ref}
         active={cardProps.active ?? selected}
-        {...knobProps.panelPadding}
+        {...layout}
         borderRadius={knobProps.borderRadius.borderRadius}
         {...cardProps}
       />
@@ -182,6 +227,17 @@ const CheckboxCard = CheckboxCardFrame.styleable<{ unstyled?: boolean; active?:
   },
 );
 
+const CheckboxCardDescriptionSized = CheckboxCardDescription.styleable((props, ref) => {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <CheckboxCardDescription
+      ref={ref}
+      size={getCardDescriptionSize(knobProps.sizeToken)}
+      {...props}
+    />
+  );
+});
+
 const CheckboxesIndicator = TamaguiCheckbox.Indicator.styleable((indicatorProps, ref) => {
   const { children, ...props } = indicatorProps;
   return (
@@ -203,7 +259,11 @@ export const Checkboxes = withStaticProperties(CheckboxesImp, {
     Indicator: CheckboxesIndicator,
     Label,
   }),
-  Card: CheckboxCard,
+  Card: withStaticProperties(CheckboxCard, {
+    Content: CheckboxCardContent,
+    Label: CheckboxCardLabel,
+    Description: CheckboxCardDescriptionSized,
+  }),
 });
 
 export { Checkbox } from "./Checkbox";

package/src/fields/ColorPicker/ColorPicker.spec.tsx

@@ -1,7 +1,11 @@
 import { act, fireEvent, waitFor } from "@testing-library/react";
+import { createElement } from "react";
 import { describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import {
+  AlphaStrip,
+  HueStrip,
+  SaturationPanel,
   hexToHsv,
   hexToRgb,
   hsvToHex,
@@ -17,6 +21,24 @@ vi.mock("@tamagui/lucide-icons-2", () => ({
   X: () => null,
 }));
 
+vi.mock("expo-linear-gradient", () => ({
+  LinearGradient: (props: {
+    colors?: string[];
+    locations?: number[];
+    start?: { x: number; y: number };
+    end?: { x: number; y: number };
+    style?: unknown;
+    testID?: string;
+  }) =>
+    createElement("div", {
+      "data-testid": props.testID ?? "expo-linear-gradient",
+      "data-colors": JSON.stringify(props.colors ?? []),
+      "data-locations": JSON.stringify(props.locations ?? null),
+      "data-start": JSON.stringify(props.start ?? null),
+      "data-end": JSON.stringify(props.end ?? null),
+    }),
+}));
+
 async function loadColorPicker() {
   return (await import("./index")).ColorPicker;
 }
@@ -88,6 +110,34 @@ describe("ColorPicker", () => {
     });
   });
 
+  it("fires canonical onChange and the deprecated onValueChange alias once when cleared", async () => {
+    const ColorPicker = await loadColorPicker();
+    const onChange = vi.fn();
+    const onValueChange = vi.fn();
+    const result = renderWithProviders(
+      <ColorPicker
+        label="Color"
+        name="color"
+        defaultValue="#112233"
+        onChange={onChange}
+        onValueChange={onValueChange}
+      />,
+    );
+
+    const triggerButton = result.container.querySelector("button");
+    expect(triggerButton).toBeTruthy();
+    await act(async () => {
+      if (triggerButton) fireEvent.click(triggerButton);
+    });
+
+    await waitFor(() => {
+      expect(onChange).toHaveBeenCalledWith("");
+    });
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledWith("");
+  });
+
   it("shows format validation error for invalid rgb value", async () => {
     const ColorPicker = await loadColorPicker();
     const result = renderWithProviders(
@@ -127,4 +177,59 @@ describe("ColorPicker", () => {
       expect(fromHex.v).toBe(100);
     });
   });
+
+  describe("gradient backgrounds", () => {
+    it("web path keeps CSS linear-gradient on saturation / hue / alpha", () => {
+      const result = renderWithProviders(
+        <>
+          <SaturationPanel hue={210} saturation={80} value={60} onChangeSV={() => {}} size={100} />
+          <HueStrip hue={210} onChangeHue={() => {}} width={100} />
+          <AlphaStrip
+            hue={210}
+            saturation={80}
+            value={60}
+            alpha={50}
+            onChangeAlpha={() => {}}
+            width={100}
+          />
+        </>,
+      );
+
+      const html = result.container.innerHTML;
+      expect(html).toContain("linear-gradient(to right, #fff,");
+      expect(html).toContain("linear-gradient(to top, #000, transparent)");
+      expect(html).toContain(hsvToHex(210, 100, 100));
+      expect(html).toMatch(/linear-gradient\(to right, #f00/);
+      expect(result.container.querySelectorAll('[data-testid="expo-linear-gradient"]').length).toBe(
+        0,
+      );
+    });
+
+    it("native path stacks expo-linear-gradient for saturation, hue, and alpha", async () => {
+      const { AlphaBackground, HueBackground, SaturationBackground } =
+        await import("./gradients.native");
+
+      const result = renderWithProviders(
+        <>
+          <SaturationBackground hueColor="#FF0000" width={100} height={100} />
+          <HueBackground width={100} height={14} />
+          <AlphaBackground hex="#00FF00" width={100} height={14} />
+        </>,
+      );
+
+      const grads = result.container.querySelectorAll('[data-testid="expo-linear-gradient"]');
+      // sat: 2 layers, hue: 1, alpha: 1
+      expect(grads.length).toBe(4);
+
+      const colorLists = [...grads].map((el) => JSON.parse(el.getAttribute("data-colors") || "[]"));
+      expect(colorLists).toEqual(
+        expect.arrayContaining([
+          ["#FFFFFF", "#FF0000"],
+          ["rgba(0,0,0,0)", "#000000"],
+          ["#FF0000", "#FFFF00", "#00FF00", "#00FFFF", "#0000FF", "#FF00FF", "#FF0000"],
+          ["rgba(0,0,0,0)", "#00FF00"],
+        ]),
+      );
+    });
+  });
 });

package/src/fields/ColorPicker/ColorPicker.stories.tsx

@@ -114,7 +114,6 @@ export const Interactive: Story = {
           <ColorPicker
             label="Pick a Color"
             value={color}
-            // @ts-expect-error controlled mode not supported
             onChange={(val: string) => {
               setColor(val);
               action("onChange")(val);
@@ -163,3 +162,9 @@ export const WithError: Story = {
     required: true,
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the field's anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  render: (args) => <ColorPicker {...args} />,
+  args: { label: "Brand Color", skeleton: true },
+};

package/src/fields/ColorPicker/gradients.native.tsx

@@ -0,0 +1,97 @@
+import { LinearGradient } from "expo-linear-gradient";
+import { StyleSheet, View as RNView } from "react-native";
+
+/**
+ * Native ColorPicker gradient fills — `expo-linear-gradient`.
+ * Web keeps CSS via `gradients.tsx` (Metro platform extension).
+ *
+ * Uses RN View + explicit width/height (not Tamagui absolute fill) so the
+ * native gradient view always gets a non-zero layout box in Expo Go.
+ */
+
+const HUE_COLORS = [
+  "#FF0000",
+  "#FFFF00",
+  "#00FF00",
+  "#00FFFF",
+  "#0000FF",
+  "#FF00FF",
+  "#FF0000",
+] as const;
+const HUE_LOCATIONS = [0, 0.17, 0.33, 0.5, 0.67, 0.83, 1] as const;
+
+const TRANSPARENT = "rgba(0,0,0,0)";
+
+export function SaturationBackground({
+  hueColor,
+  width,
+  height,
+}: {
+  hueColor: string;
+  width: number;
+  height: number;
+}) {
+  const box = { width, height };
+  return (
+    <RNView style={[styles.host, box]} pointerEvents="none">
+      <LinearGradient
+        colors={["#FFFFFF", hueColor]}
+        start={{ x: 0, y: 0.5 }}
+        end={{ x: 1, y: 0.5 }}
+        style={StyleSheet.absoluteFill}
+      />
+      <LinearGradient
+        colors={[TRANSPARENT, "#000000"]}
+        start={{ x: 0.5, y: 0 }}
+        end={{ x: 0.5, y: 1 }}
+        style={StyleSheet.absoluteFill}
+      />
+    </RNView>
+  );
+}
+
+export function HueBackground({ width, height }: { width: number; height: number }) {
+  return (
+    <LinearGradient
+      colors={[...HUE_COLORS]}
+      locations={[...HUE_LOCATIONS]}
+      start={{ x: 0, y: 0.5 }}
+      end={{ x: 1, y: 0.5 }}
+      style={[styles.host, { width, height }]}
+      pointerEvents="none"
+    />
+  );
+}
+
+export function AlphaBackground({
+  hex,
+  width,
+  height,
+}: {
+  hex: string;
+  width: number;
+  height: number;
+}) {
+  const box = { width, height };
+  return (
+    <RNView style={[styles.host, box]} pointerEvents="none">
+      <RNView style={[StyleSheet.absoluteFill, { backgroundColor: "#E5E5E5" }]} />
+      <RNView style={[StyleSheet.absoluteFill, { backgroundColor: "#BBBBBB", opacity: 0.35 }]} />
+      <LinearGradient
+        colors={[TRANSPARENT, hex]}
+        start={{ x: 0, y: 0.5 }}
+        end={{ x: 1, y: 0.5 }}
+        style={StyleSheet.absoluteFill}
+      />
+    </RNView>
+  );
+}
+
+const styles = StyleSheet.create({
+  host: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    overflow: "hidden",
+  },
+});

package/src/fields/ColorPicker/gradients.tsx

@@ -0,0 +1,78 @@
+import { View } from "tamagui";
+
+/**
+ * Web ColorPicker gradient fills — CSS `linear-gradient` backgrounds.
+ * Metro resolves `gradients.native.tsx` on iOS/Android instead.
+ *
+ * Saturation uses two stacked layers (not a comma-joined `background`) so
+ * Tamagui/style serialization cannot drop the value overlay.
+ *
+ * `width`/`height` are accepted for API parity with the native module (unused on web).
+ */
+
+const fill = {
+  position: "absolute" as const,
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+};
+
+export function SaturationBackground({
+  hueColor,
+}: {
+  hueColor: string;
+  width?: number;
+  height?: number;
+}) {
+  return (
+    <View {...fill} overflow="hidden">
+      <View
+        {...fill}
+        style={{
+          background: `linear-gradient(to right, #fff, ${hueColor})`,
+        }}
+      />
+      <View
+        {...fill}
+        style={{
+          background: "linear-gradient(to top, #000, transparent)",
+        }}
+      />
+    </View>
+  );
+}
+
+export function HueBackground(_props: { width?: number; height?: number }) {
+  return (
+    <View
+      {...fill}
+      style={{
+        background:
+          "linear-gradient(to right, #f00 0%, #ff0 17%, #0f0 33%, #0ff 50%, #00f 67%, #f0f 83%, #f00 100%)",
+      }}
+    />
+  );
+}
+
+export function AlphaBackground({ hex }: { hex: string; width?: number; height?: number }) {
+  return (
+    <>
+      <View
+        {...fill}
+        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",
+        }}
+      />
+      <View
+        {...fill}
+        style={{
+          background: `linear-gradient(to right, transparent, ${hex})`,
+        }}
+      />
+    </>
+  );
+}