@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/Checkbox/Checkbox.tsx

@@ -1,6 +1,5 @@
 import { CheckIcon as CheckRegular, MinusIcon as MinusRegular } from "@phosphor-icons/react";
 import type { AnyFormApi } from "../../types";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
 import type { ReactNode } from "react";
 import { useMemo } from "react";
 import type {
@@ -10,7 +9,18 @@ import type {
   LabelProps,
   SizeTokens,
 } from "tamagui";
-import { Checkbox as TamaguiCheckbox, Label, View, XStack, getVariable, useTheme } from "tamagui";
+import {
+  Checkbox as TamaguiCheckbox,
+  Label,
+  View,
+  XStack,
+  getVariable,
+  getVariableValue,
+  isWeb,
+  useTheme,
+} from "tamagui";
+import { getSize } from "@tamagui/get-token";
+import { useIsInTableCell } from "../../shared/tableCellContext";
 import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { formCommonColors, formControlColors } from "../../shared/colorRamps";
@@ -40,6 +50,12 @@ export interface CheckboxProps {
   id?: string;
   checked?: CheckedState;
   defaultValue?: boolean | "indeterminate";
+  /**
+   * Canonical change handler, consistent with the rest of the field family
+   * (Input/Select/Switch all use `onChange`). Prefer this.
+   */
+  onChange?: (checked: CheckedState) => void;
+  /** @deprecated Use `onChange` instead. Kept as an alias for the tamagui/Radix name. */
   onCheckedChange?: (checked: CheckedState) => void;
   onBlur?: (...args: any[]) => void;
   checkboxProps?: Omit<TamaguiCheckboxProps, "children" | "checked" | "id" | "onCheckedChange">;
@@ -52,6 +68,21 @@ export interface CheckboxProps {
   compact?: boolean;
 }
 
+/**
+ * Gap between the checkbox control and its label, by space knob.
+ * Shared with the skeleton branches so loading geometry mirrors the
+ * real anatomy (LC-20 SKELETON-MIRRORS-ANATOMY).
+ */
+export function getCheckboxInlineGap(space: string): string {
+  const inlineGapMap: Record<string, string> = {
+    none: "$1",
+    small: "$1.5",
+    medium: "$2",
+    large: "$2.5",
+  };
+  return inlineGapMap[space] || "$2";
+}
+
 export function Checkbox({
   name,
   form: formProp,
@@ -67,6 +98,7 @@ export function Checkbox({
   id: idProp,
   checked,
   defaultValue,
+  onChange,
   onCheckedChange,
   onBlur,
   checkboxProps,
@@ -75,7 +107,13 @@ export function Checkbox({
   skeleton,
   compact,
 }: CheckboxProps) {
-  const { resolvedForm, knobProps, control, text, elevation, id } = useFormField({
+  // Canonical `onChange` and the alias `onCheckedChange` both fire from a
+  // single emit site (same reconciliation as Switch).
+  const handleValueChange = (val: CheckedState) => {
+    onChange?.(val);
+    onCheckedChange?.(val);
+  };
+  const { resolvedForm, knobProps, control, text, elevation, disabledState, id } = useFormField({
     form: formProp,
     id: idProp,
     compact,
@@ -97,13 +135,7 @@ export function Checkbox({
     cappedRadius === 0
       ? { borderWidth: knobProps.borderRadius.borderWidth, borderRadius: 0 }
       : { borderWidth: knobProps.borderRadius.borderWidth, borderRadius: cappedRadius };
-  const inlineGapMap: Record<string, string> = {
-    none: "$1",
-    small: "$1.5",
-    medium: "$2",
-    large: "$2.5",
-  };
-  const inlineGap = inlineGapMap[knobProps.space] || "$2";
+  const inlineGap = getCheckboxInlineGap(knobProps.space);
   const baseLabelColor = error ? formCommonColors.error : knobProps.textAccentColor;
   const labelHoverStyle = { color: baseLabelColor, ...text.hoverKnobProps };
   const labelPressStyle = { color: baseLabelColor, ...text.pressKnobProps };
@@ -140,12 +172,85 @@ export function Checkbox({
     );
   };
 
+  // Pressable-vs-glyph split (SP-FIXED / WCAG 2.5.5, same anatomy as
+  // RadioGroup): the role=checkbox frame is ALWAYS a 44px transparent
+  // pressable target; the visible box renders as an inner glyph at the
+  // checkbox's own computed size (tamagui scaleSize 0.45), so visual density
+  // is unchanged. Cells (chromeless) and plain forms share the treatment —
+  // the earlier cell-only split left the plain checkbox at a 20px target.
+  const inTableCell = useIsInTableCell();
+  const targetSize = 44;
+  const glyphSize = Math.round(getVariableValue(getSize(resolvedSize as SizeTokens)) * 0.45);
+  const targetFrameProps = {
+    width: targetSize,
+    height: targetSize,
+    minWidth: targetSize,
+    minHeight: targetSize,
+    padding: 0,
+    borderWidth: 0,
+    backgroundColor: "transparent",
+    alignItems: "center",
+    justifyContent: "center",
+    activeStyle: { backgroundColor: "transparent" },
+  } as const;
+  // Interaction-state tints stay off the (invisible) 44px frame; the knob
+  // state props (ring/halo) still apply around the target.
+  const stateBaseStyle = { backgroundColor: "transparent" };
+  const glyphBox = (currentChecked: CheckedState | undefined) => (
+    <View
+      width={glyphSize}
+      height={glyphSize}
+      {...knobProps.inputSurface}
+      {...resolvedRadius}
+      backgroundColor={knobProps.outlined ? "transparent" : formControlColors.background}
+      borderColor={formControlColors.border}
+      alignItems="center"
+      justifyContent="center"
+    >
+      {renderIndicator(currentChecked)}
+    </View>
+  );
+  // Elevation wraps the visible glyph, never the invisible target (cells
+  // keep elevation suppressed as before).
+  const renderControlContent = (currentChecked: CheckedState | undefined) =>
+    elevationWrapperProps.elevation && !inTableCell ? (
+      <View
+        borderRadius={resolvedRadius.borderRadius ?? knobProps.borderRadius.borderRadius}
+        {...elevationWrapperProps}
+      >
+        {glyphBox(currentChecked)}
+      </View>
+    ) : (
+      glyphBox(currentChecked)
+    );
+
+  // iOS: Tamagui's checkbox emits role="checkbox" + aria-checked but never
+  // `accessible` — without it the box is not an accessibility element and
+  // VoiceOver skips it entirely. htmlFor label wiring is also web-only, so
+  // carry the label/error strings on the control itself.
+  const nativeCheckboxA11y = (errorText?: string) =>
+    isWeb
+      ? undefined
+      : {
+          accessible: true,
+          accessibilityState: { disabled: !!disabled },
+          ...(typeof label === "string"
+            ? { accessibilityLabel: `${label}${required ? " *" : ""}` }
+            : undefined),
+          ...(errorText || helperText ? { accessibilityHint: errorText ?? helperText } : undefined),
+        };
+
   if (skeleton) {
+    // Mirror the real anatomy (LC-20): same control size, the same clamped
+    // radius the real box uses, the same box↔label gap — and the 44px
+    // pressable target box around the 20px glyph (same as RadioGroup).
     return (
       <FieldLayout id={id} size={size} knobProps={knobProps} compactSpacing>
-        <XStack gap="$2" alignItems="center">
-          <Skeleton variant="rounded" width={20} height={20} />
-          {label && <Skeleton variant="text" width="40%" height={14} />}
+        <XStack gap={inlineGap} alignItems="center">
+          <View width={targetSize} height={targetSize} alignItems="center" justifyContent="center">
+            <Skeleton variant="rounded" width={20} height={20} borderRadius={cappedRadius} />
+          </View>
+          {label && <Skeleton variant="text" width={96} height={14} />}
         </XStack>
       </FieldLayout>
     );
@@ -157,41 +262,39 @@ export function Checkbox({
 
     const checkboxEl = (
       <CheckboxFieldFrame
-        {...knobProps.inputSurface}
         size={resolvedSize as SizeTokens}
-        {...resolvedRadius}
-        outlined={knobProps.outlined}
         transition={knobProps.transition}
         {...(clampRadiusInStateProps(control.hoverKnobProps, 2) && {
           hoverStyle: {
-            backgroundColor: formControlColors.background,
-            borderColor: formControlColors.border,
+            ...stateBaseStyle,
             ...clampRadiusInStateProps(control.hoverKnobProps, 2),
           },
         })}
         {...(clampRadiusInStateProps(control.pressKnobProps, 2) && {
           pressStyle: {
-            backgroundColor: formControlColors.background,
-            borderColor: formControlColors.border,
+            ...stateBaseStyle,
             ...clampRadiusInStateProps(control.pressKnobProps, 2),
           },
         })}
         {...(clampRadiusInStateProps(control.focusKnobProps, 2) && {
           focusStyle: {
-            backgroundColor: formControlColors.background,
-            borderColor: formControlColors.border,
+            ...stateBaseStyle,
             ...clampRadiusInStateProps(control.focusKnobProps, 2),
           },
         })}
         {...(clampRadiusInStateProps(control.focusVisibleKnobProps, 2) && {
           focusVisibleStyle: {
-            backgroundColor: formControlColors.background,
-            borderColor: formControlColors.border,
+            ...stateBaseStyle,
             ...clampRadiusInStateProps(control.focusVisibleKnobProps, 2),
           },
         })}
+        {...targetFrameProps}
         {...checkboxProps}
         disabled={disabled}
+        // LC-40 DISABLED-VISIBLE: the box is text-free chrome — dim it while
+        // the sibling label stays readable (keepLabel); dimWhole dims the
+        // whole assembly via FieldLayout instead.
+        {...(disabled ? disabledState.chromeKnobProps : undefined)}
         id={id}
         {...(isControlled
           ? { checked }
@@ -202,25 +305,16 @@ export function Checkbox({
         {...(readOnly ? { "aria-readonly": true } : undefined)}
         aria-required={required || undefined}
         aria-invalid={!!error || undefined}
+        {...nativeCheckboxA11y(typeof error === "string" && error ? error : undefined)}
         onCheckedChange={(val) => {
           if (disabled || readOnly) return;
-          onCheckedChange?.(val);
+          handleValueChange(val);
         }}
         {...(onBlur ? { onBlur } : undefined)}
       >
-        {renderIndicator(checked ?? (defaultValue as CheckedState | undefined))}
+        {renderControlContent(checked ?? (defaultValue as CheckedState | undefined))}
       </CheckboxFieldFrame>
     );
-    const checkboxControl = elevationWrapperProps.elevation ? (
-      <View
-        borderRadius={resolvedRadius.borderRadius ?? knobProps.borderRadius.borderRadius}
-        {...elevationWrapperProps}
-      >
-        {checkboxEl}
-      </View>
-    ) : (
-      checkboxEl
-    );
 
     const hasElevation = !!elevationWrapperProps.elevation;
     const checkboxRow = (
@@ -228,8 +322,15 @@ export function Checkbox({
         gap={inlineGap}
         alignItems="center"
         {...(hasElevation && { overflow: "visible" as const })}
+        // LC-40: when no FieldLayout wraps this row (no error/helper), the row
+        // IS the disabled assembly — carry the dimWhole assembly fragment here
+        // (empty under keepLabel) so the disabled control stays visible.
+        {...(disabled && !needsFieldLayout ? disabledState.assemblyKnobProps : undefined)}
+        {...(disabled && !needsFieldLayout
+          ? { "data-disabled-dimmed": disabledState.style === "dimWhole" ? "true" : "false" }
+          : undefined)}
       >
-        {checkboxControl}
+        {checkboxEl}
         {label && (
           <Label
             htmlFor={id}
@@ -240,7 +341,7 @@ export function Checkbox({
             pressStyle={labelPressStyle}
             focusStyle={labelFocusStyle}
             focusVisibleStyle={labelFocusVisibleStyle}
-            paddingRight="$1"
+            paddingInlineEnd="$1"
             {...labelProps}
           >
             {label}
@@ -253,7 +354,16 @@ export function Checkbox({
     if (!needsFieldLayout) return checkboxRow;
 
     return (
-      <FieldLayout id={id} error={error} helperText={helperText} size={size} knobProps={knobProps}>
+      <FieldLayout
+        id={id}
+        error={error}
+        helperText={helperText}
+        size={size}
+        knobProps={knobProps}
+        // LC-40: FieldLayout owns the dimWhole assembly dim (keepLabel pins
+        // the sibling label/helper readable) — it needs the disabled state.
+        disabled={disabled}
+      >
         {checkboxRow}
       </FieldLayout>
     );
@@ -297,6 +407,8 @@ export function Checkbox({
             helperText={helperText}
             size={size}
             knobProps={knobProps}
+            // LC-40: see standalone branch — FieldLayout carries dimWhole.
+            disabled={disabled}
           >
             <XStack
               gap={inlineGap}
@@ -306,71 +418,61 @@ export function Checkbox({
               {(() => {
                 const checkboxElement = (
                   <CheckboxFieldFrame
-                    {...knobProps.inputSurface}
                     size={resolvedSize as SizeTokens}
-                    {...resolvedRadius}
-                    outlined={knobProps.outlined}
                     transition={knobProps.transition}
                     {...(clampRadiusInStateProps(control.hoverKnobProps, 2) && {
                       hoverStyle: {
-                        backgroundColor: formControlColors.background,
-                        borderColor: formControlColors.border,
+                        ...stateBaseStyle,
                         ...clampRadiusInStateProps(control.hoverKnobProps, 2),
                       },
                     })}
                     {...(clampRadiusInStateProps(control.pressKnobProps, 2) && {
                       pressStyle: {
-                        backgroundColor: formControlColors.background,
-                        borderColor: formControlColors.border,
+                        ...stateBaseStyle,
                         ...clampRadiusInStateProps(control.pressKnobProps, 2),
                       },
                     })}
                     {...(clampRadiusInStateProps(control.focusKnobProps, 2) && {
                       focusStyle: {
-                        backgroundColor: formControlColors.background,
-                        borderColor: formControlColors.border,
+                        ...stateBaseStyle,
                         ...clampRadiusInStateProps(control.focusKnobProps, 2),
                       },
                     })}
                     {...(clampRadiusInStateProps(control.focusVisibleKnobProps, 2) && {
                       focusVisibleStyle: {
-                        backgroundColor: formControlColors.background,
-                        borderColor: formControlColors.border,
+                        ...stateBaseStyle,
                         ...clampRadiusInStateProps(control.focusVisibleKnobProps, 2),
                       },
                     })}
+                    {...targetFrameProps}
                     {...checkboxProps}
                     disabled={disabled}
+                    // LC-40: dim the box chrome; label/helper stay readable.
+                    {...(disabled ? disabledState.chromeKnobProps : undefined)}
                     id={id}
                     checked={resolvedChecked}
                     {...(readOnly ? { pointerEvents: "none" as const } : undefined)}
                     {...(readOnly ? { "aria-readonly": true } : undefined)}
                     aria-required={required || undefined}
                     aria-invalid={!!resolvedError || undefined}
+                    {...nativeCheckboxA11y(
+                      typeof resolvedError === "string" && resolvedError
+                        ? resolvedError
+                        : undefined,
+                    )}
                     onCheckedChange={(newChecked) => {
                       if (disabled || readOnly) return;
                       const fieldValue =
                         newChecked === "indeterminate" ? false : newChecked === true;
                       field.handleChange(fieldValue as any);
-                      onCheckedChange?.(newChecked);
+                      handleValueChange(newChecked);
                     }}
                     onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
                   >
-                    {renderIndicator(resolvedChecked)}
+                    {renderControlContent(resolvedChecked)}
                   </CheckboxFieldFrame>
                 );
-                return elevationWrapperProps.elevation ? (
-                  <View
-                    borderRadius={
-                      resolvedRadius.borderRadius ?? knobProps.borderRadius.borderRadius
-                    }
-                    {...elevationWrapperProps}
-                  >
-                    {checkboxElement}
-                  </View>
-                ) : (
-                  checkboxElement
-                );
+                return checkboxElement;
               })()}
               {label && (
                 <Label
@@ -382,7 +484,7 @@ export function Checkbox({
                   pressStyle={resolvedLabelPressStyle}
                   focusStyle={resolvedLabelFocusStyle}
                   focusVisibleStyle={resolvedLabelFocusVisibleStyle}
-                  paddingRight="$1"
+                  paddingInlineEnd="$1"
                   {...labelProps}
                 >
                   {label}

package/src/fields/Checkbox/CheckboxCard.tsx

@@ -0,0 +1,90 @@
+import type { FontSizeTokens, SizeTokens } from "tamagui";
+import { Paragraph, View, styled } from "tamagui";
+import { formCardColors, formCommonColors } from "../../shared/colorRamps";
+
+/**
+ * SELECTION-CARD anatomy (LC-22): the control sits in a fixed leading slot,
+ * top-aligned with the first label line; the bold label sits immediately to
+ * its right; the muted description sits under the label sharing the label's
+ * left edge. Compact padding, whole card interactive. Shared by the compound
+ * `Checkboxes.Card`, `CheckboxGroup card`, and `RadioGroup card`.
+ */
+export const CheckboxCardFrame = styled(View, {
+  flexDirection: "row",
+  alignItems: "flex-start",
+  gap: "$3",
+  cursor: "pointer",
+  width: "100%",
+  paddingVertical: "$3",
+  paddingHorizontal: "$3.5",
+  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,
+});
+
+/** Text column right of the control: label line, then description. */
+export const CheckboxCardContent = styled(View, {
+  flexDirection: "column",
+  flex: 1,
+  minWidth: 0,
+  gap: "$0.5",
+});
+
+/** Bold first line, right of the control. */
+export const CheckboxCardLabel = styled(Paragraph, {
+  fontWeight: "600",
+  color: "$color12",
+  lineHeight: 20,
+});
+
+/** Muted helper-tier line under the label, sharing its left edge. */
+export const CheckboxCardDescription = styled(Paragraph, {
+  color: formCommonColors.muted,
+});
+
+const helperSizeMap: Record<string, FontSizeTokens> = {
+  $1: "$1",
+  $2: "$1",
+  $3: "$2",
+  $4: "$3",
+  $true: "$3",
+  $5: "$4",
+  $6: "$5",
+};
+
+/** T-HELPER tier for the description, one step under the field size. */
+export function getCardDescriptionSize(size?: SizeTokens): FontSizeTokens {
+  if (!size) return "$2";
+  return helperSizeMap[String(size)] ?? "$2";
+}
+
+/**
+ * Compact card metrics from the space knob (~$3/$3.5 vertical) — deliberately
+ * tighter than `panelPadding`, which is panel-scale and reads as dead space
+ * around a single row of text.
+ */
+export function getCheckboxCardLayout(space: string): {
+  paddingVertical: string;
+  paddingHorizontal: string;
+  gap: string;
+} {
+  const map: Record<string, { paddingVertical: string; paddingHorizontal: string; gap: string }> = {
+    none: { paddingVertical: "$2.5", paddingHorizontal: "$3", gap: "$2.5" },
+    small: { paddingVertical: "$3", paddingHorizontal: "$3.5", gap: "$3" },
+    medium: { paddingVertical: "$3", paddingHorizontal: "$3.5", gap: "$3" },
+    large: { paddingVertical: "$3.5", paddingHorizontal: "$4", gap: "$3.5" },
+  };
+  return map[space] ?? map.medium;
+}