@multiplatform.one/forms 6.0.0

package/src/fields/Checkbox/Checkbox.tsx

@@ -0,0 +1,398 @@
+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 {
+  CheckedState,
+  CheckboxProps as TamaguiCheckboxProps,
+  FontSizeTokens,
+  LabelProps,
+  SizeTokens,
+} from "tamagui";
+import { Checkbox as TamaguiCheckbox, Label, View, XStack, getVariable, useTheme } from "tamagui";
+import { Skeleton } from "../../Skeleton";
+import { Field, FieldLayout } from "../../fieldLayout";
+import { formCommonColors, formControlColors } from "../../shared/colorRamps";
+import {
+  clampRadiusForControl,
+  clampRadiusInStateProps,
+  getElevationWrapperProps,
+  getFieldError,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import { CheckboxFieldFrame } from "./CheckboxFieldFrame";
+
+export interface CheckboxProps {
+  name?: string;
+  form?: AnyFormApi;
+  validators?: Record<string, unknown>;
+  label?: ReactNode;
+  labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+  helperText?: string;
+  error?: string | boolean;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  size?: SizeTokens;
+  id?: string;
+  checked?: CheckedState;
+  defaultValue?: boolean | "indeterminate";
+  onCheckedChange?: (checked: CheckedState) => void;
+  onBlur?: (...args: any[]) => void;
+  checkboxProps?: Omit<TamaguiCheckboxProps, "children" | "checked" | "id" | "onCheckedChange">;
+  children?: ReactNode;
+  /** Force hard-angled checkbox. Defaults to `true` when the theme knob `borderRadius` is `"none"`. */
+  pointy?: boolean;
+  /** When true, renders a skeleton placeholder instead of the checkbox */
+  skeleton?: boolean;
+  /** When true, uses compact sizing */
+  compact?: boolean;
+}
+
+export function Checkbox({
+  name,
+  form: formProp,
+  validators,
+  label,
+  labelProps,
+  helperText,
+  error,
+  required,
+  disabled,
+  readOnly,
+  size,
+  id: idProp,
+  checked,
+  defaultValue,
+  onCheckedChange,
+  onBlur,
+  checkboxProps,
+  children,
+  pointy,
+  skeleton,
+  compact,
+}: CheckboxProps) {
+  const { resolvedForm, knobProps, control, text, elevation, id } = useFormField({
+    form: formProp,
+    id: idProp,
+    compact,
+  });
+  const resolvedValidators = useResolvedValidators(required, validators, label, name, (v) => !v);
+  const resolvedPointy = pointy ?? knobProps.pointy;
+
+  const checkboxSizeMap: Record<string, SizeTokens> = {
+    $2: "$3" as SizeTokens,
+    $3: "$3" as SizeTokens,
+    $4: "$true" as SizeTokens,
+    $5: "$5" as SizeTokens,
+  };
+  const resolvedSize =
+    size || checkboxSizeMap[knobProps.sizeToken] || (knobProps.sizeToken as SizeTokens);
+  const radiusToken = knobProps.borderRadius.borderRadius;
+  const cappedRadius = resolvedPointy ? 0 : clampRadiusForControl(radiusToken, 2);
+  const resolvedRadius =
+    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 baseLabelColor = error ? formCommonColors.error : knobProps.textAccentColor;
+  const labelHoverStyle = { color: baseLabelColor, ...text.hoverKnobProps };
+  const labelPressStyle = { color: baseLabelColor, ...text.pressKnobProps };
+  const labelFocusStyle = { color: baseLabelColor, ...text.focusKnobProps };
+  const labelFocusVisibleStyle = { color: baseLabelColor, ...text.focusVisibleKnobProps };
+  const tamaguiTheme = useTheme();
+  const elevationWrapperProps = useMemo(
+    () => getElevationWrapperProps(knobProps, elevation),
+    [knobProps, elevation],
+  );
+  const accentTokenKey = (knobProps.textAccentColor ?? "$color").replace("$", "");
+  const indicatorColor = getVariable(
+    tamaguiTheme[accentTokenKey as any]?.get("web") ?? tamaguiTheme.color?.get("web"),
+  );
+  const indicatorWeight =
+    knobProps.textWeight.fontWeight === "700"
+      ? "bold"
+      : knobProps.textWeight.fontWeight === "400"
+        ? "regular"
+        : "light";
+
+  const renderIndicator = (currentChecked: CheckedState | undefined) => {
+    if (children) return children;
+    return (
+      <TamaguiCheckbox.Indicator
+        {...(knobProps.transition ? { animation: knobProps.transition } : undefined)}
+      >
+        {currentChecked === "indeterminate" ? (
+          <MinusRegular color={indicatorColor} weight={indicatorWeight} />
+        ) : (
+          <CheckRegular color={indicatorColor} weight={indicatorWeight} />
+        )}
+      </TamaguiCheckbox.Indicator>
+    );
+  };
+
+  if (skeleton) {
+    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>
+      </FieldLayout>
+    );
+  }
+
+  if (!resolvedForm || !name) {
+    const isControlled = checked !== undefined;
+    const needsFieldLayout = !!(error || helperText);
+
+    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,
+            ...clampRadiusInStateProps(control.hoverKnobProps, 2),
+          },
+        })}
+        {...(clampRadiusInStateProps(control.pressKnobProps, 2) && {
+          pressStyle: {
+            backgroundColor: formControlColors.background,
+            borderColor: formControlColors.border,
+            ...clampRadiusInStateProps(control.pressKnobProps, 2),
+          },
+        })}
+        {...(clampRadiusInStateProps(control.focusKnobProps, 2) && {
+          focusStyle: {
+            backgroundColor: formControlColors.background,
+            borderColor: formControlColors.border,
+            ...clampRadiusInStateProps(control.focusKnobProps, 2),
+          },
+        })}
+        {...(clampRadiusInStateProps(control.focusVisibleKnobProps, 2) && {
+          focusVisibleStyle: {
+            backgroundColor: formControlColors.background,
+            borderColor: formControlColors.border,
+            ...clampRadiusInStateProps(control.focusVisibleKnobProps, 2),
+          },
+        })}
+        {...checkboxProps}
+        disabled={disabled}
+        id={id}
+        {...(isControlled
+          ? { checked }
+          : defaultValue !== undefined
+            ? { defaultChecked: defaultValue as CheckedState }
+            : undefined)}
+        {...(readOnly ? { pointerEvents: "none" as const } : undefined)}
+        {...(readOnly ? { "aria-readonly": true } : undefined)}
+        aria-required={required || undefined}
+        aria-invalid={!!error || undefined}
+        onCheckedChange={(val) => {
+          if (disabled || readOnly) return;
+          onCheckedChange?.(val);
+        }}
+        {...(onBlur ? { onBlur } : undefined)}
+      >
+        {renderIndicator(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 = (
+      <XStack
+        gap={inlineGap}
+        alignItems="center"
+        {...(hasElevation && { overflow: "visible" as const })}
+      >
+        {checkboxControl}
+        {label && (
+          <Label
+            htmlFor={id}
+            size={(size || "$true") as FontSizeTokens}
+            {...knobProps.textWeight}
+            color={baseLabelColor}
+            hoverStyle={labelHoverStyle}
+            pressStyle={labelPressStyle}
+            focusStyle={labelFocusStyle}
+            focusVisibleStyle={labelFocusVisibleStyle}
+            paddingRight="$1"
+            {...labelProps}
+          >
+            {label}
+            {required && " *"}
+          </Label>
+        )}
+      </XStack>
+    );
+
+    if (!needsFieldLayout) return checkboxRow;
+
+    return (
+      <FieldLayout id={id} error={error} helperText={helperText} size={size} knobProps={knobProps}>
+        {checkboxRow}
+      </FieldLayout>
+    );
+  }
+
+  return (
+    <Field
+      form={resolvedForm}
+      name={name}
+      defaultValue={defaultValue}
+      validators={resolvedValidators}
+    >
+      {(field) => {
+        const resolvedError = getFieldError(field, error);
+        const resolvedChecked =
+          checked !== undefined ? checked : (field.state.value as CheckedState);
+        const resolvedLabelColor = resolvedError
+          ? formCommonColors.error
+          : knobProps.textAccentColor;
+        const resolvedLabelHoverStyle = {
+          color: resolvedLabelColor,
+          ...text.hoverKnobProps,
+        };
+        const resolvedLabelPressStyle = {
+          color: resolvedLabelColor,
+          ...text.pressKnobProps,
+        };
+        const resolvedLabelFocusStyle = {
+          color: resolvedLabelColor,
+          ...text.focusKnobProps,
+        };
+        const resolvedLabelFocusVisibleStyle = {
+          color: resolvedLabelColor,
+          ...text.focusVisibleKnobProps,
+        };
+
+        return (
+          <FieldLayout
+            id={id}
+            error={resolvedError}
+            helperText={helperText}
+            size={size}
+            knobProps={knobProps}
+          >
+            <XStack
+              gap={inlineGap}
+              alignItems="center"
+              {...(elevationWrapperProps.elevation && { overflow: "visible" as const })}
+            >
+              {(() => {
+                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,
+                        ...clampRadiusInStateProps(control.hoverKnobProps, 2),
+                      },
+                    })}
+                    {...(clampRadiusInStateProps(control.pressKnobProps, 2) && {
+                      pressStyle: {
+                        backgroundColor: formControlColors.background,
+                        borderColor: formControlColors.border,
+                        ...clampRadiusInStateProps(control.pressKnobProps, 2),
+                      },
+                    })}
+                    {...(clampRadiusInStateProps(control.focusKnobProps, 2) && {
+                      focusStyle: {
+                        backgroundColor: formControlColors.background,
+                        borderColor: formControlColors.border,
+                        ...clampRadiusInStateProps(control.focusKnobProps, 2),
+                      },
+                    })}
+                    {...(clampRadiusInStateProps(control.focusVisibleKnobProps, 2) && {
+                      focusVisibleStyle: {
+                        backgroundColor: formControlColors.background,
+                        borderColor: formControlColors.border,
+                        ...clampRadiusInStateProps(control.focusVisibleKnobProps, 2),
+                      },
+                    })}
+                    {...checkboxProps}
+                    disabled={disabled}
+                    id={id}
+                    checked={resolvedChecked}
+                    {...(readOnly ? { pointerEvents: "none" as const } : undefined)}
+                    {...(readOnly ? { "aria-readonly": true } : undefined)}
+                    aria-required={required || undefined}
+                    aria-invalid={!!resolvedError || undefined}
+                    onCheckedChange={(newChecked) => {
+                      if (disabled || readOnly) return;
+                      const fieldValue =
+                        newChecked === "indeterminate" ? false : newChecked === true;
+                      field.handleChange(fieldValue as any);
+                      onCheckedChange?.(newChecked);
+                    }}
+                    onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+                  >
+                    {renderIndicator(resolvedChecked)}
+                  </CheckboxFieldFrame>
+                );
+                return elevationWrapperProps.elevation ? (
+                  <View
+                    borderRadius={
+                      resolvedRadius.borderRadius ?? knobProps.borderRadius.borderRadius
+                    }
+                    {...elevationWrapperProps}
+                  >
+                    {checkboxElement}
+                  </View>
+                ) : (
+                  checkboxElement
+                );
+              })()}
+              {label && (
+                <Label
+                  htmlFor={id}
+                  size={(size || "$true") as FontSizeTokens}
+                  {...knobProps.textWeight}
+                  color={resolvedLabelColor}
+                  hoverStyle={resolvedLabelHoverStyle}
+                  pressStyle={resolvedLabelPressStyle}
+                  focusStyle={resolvedLabelFocusStyle}
+                  focusVisibleStyle={resolvedLabelFocusVisibleStyle}
+                  paddingRight="$1"
+                  {...labelProps}
+                >
+                  {label}
+                  {required && " *"}
+                </Label>
+              )}
+            </XStack>
+          </FieldLayout>
+        );
+      }}
+    </Field>
+  );
+}

package/src/fields/Checkbox/CheckboxFieldFrame.tsx

@@ -0,0 +1,38 @@
+import { Checkbox as TamaguiCheckbox, styled } from "tamagui";
+import { formControlColors } from "../../shared/colorRamps";
+
+export const CheckboxFieldFrame = styled(TamaguiCheckbox, {
+  backgroundColor: formControlColors.background,
+  borderColor: formControlColors.border,
+  hoverStyle: {
+    backgroundColor: formControlColors.background,
+    borderColor: formControlColors.border,
+  },
+  pressStyle: {
+    backgroundColor: formControlColors.background,
+    borderColor: formControlColors.border,
+  },
+  focusStyle: {
+    backgroundColor: formControlColors.background,
+    borderColor: formControlColors.border,
+  },
+  focusVisibleStyle: {
+    backgroundColor: formControlColors.background,
+    borderColor: formControlColors.border,
+  },
+  activeStyle: {
+    backgroundColor: formControlColors.background,
+    borderColor: formControlColors.border,
+  },
+  variants: {
+    outlined: {
+      true: {
+        backgroundColor: "transparent",
+        hoverStyle: { backgroundColor: "transparent", borderColor: formControlColors.border },
+        pressStyle: { backgroundColor: "transparent", borderColor: formControlColors.border },
+        focusStyle: { backgroundColor: "transparent", borderColor: formControlColors.border },
+        activeStyle: { backgroundColor: "transparent", borderColor: formControlColors.border },
+      },
+    },
+  } as const,
+});

package/src/fields/Checkbox/CheckboxGroup.tsx

@@ -0,0 +1,198 @@
+import type { ReactNode } from "react";
+import { useCallback } from "react";
+import type {
+  CheckedState,
+  CheckboxProps as TamaguiCheckboxProps,
+  LabelProps,
+  SizeTokens,
+} from "tamagui";
+import { XStack, YStack } from "tamagui";
+import { Field, FieldLayout } from "../../fieldLayout";
+import { Skeleton } from "../../Skeleton";
+import type { AnyFormApi } from "../../types";
+import {
+  getFieldError,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import { Checkbox } from "./Checkbox";
+
+export interface CheckboxGroupOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+}
+
+export interface CheckboxGroupProps {
+  name?: string;
+  form?: AnyFormApi;
+  validators?: Record<string, unknown>;
+  label?: ReactNode;
+  labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+  helperText?: string;
+  error?: string | boolean;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  size?: SizeTokens;
+  id?: string;
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?: (value: string[]) => void;
+  onBlur?: (...args: any[]) => void;
+  options?: CheckboxGroupOption[];
+  orientation?: "horizontal" | "vertical";
+  checkboxProps?: Omit<TamaguiCheckboxProps, "checked" | "id" | "onCheckedChange" | "children">;
+  children?: ReactNode;
+  skeleton?: boolean;
+  /** When true, uses compact sizing */
+  compact?: boolean;
+}
+
+export function CheckboxGroup({
+  name,
+  form: formProp,
+  validators,
+  label,
+  labelProps,
+  helperText,
+  error,
+  required,
+  disabled,
+  readOnly,
+  size,
+  id: idProp,
+  value,
+  defaultValue,
+  onValueChange,
+  onBlur,
+  options,
+  orientation = "vertical",
+  checkboxProps,
+  children,
+  skeleton,
+  compact,
+}: CheckboxGroupProps) {
+  const { resolvedForm, knobProps, id } = useFormField({
+    form: formProp,
+    id: idProp,
+    compact,
+  });
+  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+
+  if (skeleton) {
+    const optionCount = options?.length ?? 3;
+    const Container = orientation === "horizontal" ? XStack : YStack;
+    return (
+      <FieldLayout id={id} label={label} size={size} knobProps={knobProps}>
+        <Container gap="$2">
+          {Array.from({ length: optionCount }, (_, i) => (
+            <XStack key={i} gap="$2" alignItems="center">
+              <Skeleton variant="rounded" width={20} height={20} />
+              <Skeleton variant="text" width="50%" height={14} />
+            </XStack>
+          ))}
+        </Container>
+      </FieldLayout>
+    );
+  }
+
+  const toggleValue = useCallback(
+    (currentValues: string[], optionValue: string, checked: CheckedState) => {
+      if (checked === true) {
+        return [...currentValues, optionValue];
+      }
+      return currentValues.filter((v) => v !== optionValue);
+    },
+    [],
+  );
+
+  const renderItems = (currentValues: string[], handleChange?: (newValues: string[]) => void) => {
+    if (children) return children;
+    if (!options) return null;
+
+    const Container = orientation === "horizontal" ? XStack : YStack;
+
+    return (
+      <Container gap="$2">
+        {options.map((option) => {
+          const itemId = `${id}-${option.value}`;
+          const isChecked = currentValues.includes(option.value);
+          const isDisabled = disabled || option.disabled;
+
+          return (
+            <Checkbox
+              key={option.value}
+              label={option.label}
+              id={itemId}
+              checked={isChecked}
+              onCheckedChange={(checked) => {
+                if (isDisabled || readOnly) return;
+                const newValues = toggleValue(currentValues, option.value, checked);
+                handleChange?.(newValues);
+                onValueChange?.(newValues);
+              }}
+              disabled={isDisabled}
+              readOnly={readOnly}
+              size={size}
+              checkboxProps={checkboxProps}
+            />
+          );
+        })}
+      </Container>
+    );
+  };
+
+  if (!resolvedForm || !name) {
+    const currentValues = value ?? defaultValue ?? [];
+    return (
+      <FieldLayout
+        id={id}
+        label={label}
+        labelProps={labelProps}
+        error={error}
+        required={required}
+        helperText={helperText}
+        size={size}
+        knobProps={knobProps}
+        onBlur={onBlur}
+      >
+        {renderItems(currentValues, onValueChange)}
+      </FieldLayout>
+    );
+  }
+
+  return (
+    <Field
+      form={resolvedForm}
+      name={name}
+      defaultValue={defaultValue ?? []}
+      validators={resolvedValidators}
+    >
+      {(field) => {
+        const resolvedError = getFieldError(field, error);
+        const fieldValues = (field.state.value as string[]) ?? [];
+        const currentValues = value !== undefined ? value : fieldValues;
+
+        return (
+          <FieldLayout
+            id={id}
+            label={label}
+            labelProps={labelProps}
+            error={resolvedError}
+            required={required}
+            helperText={helperText}
+            size={size}
+            knobProps={knobProps}
+            onBlur={mergeFieldHandler(field, "handleBlur", onBlur)}
+          >
+            {renderItems(currentValues, (newValues) => {
+              field.handleChange(newValues as any);
+            })}
+          </FieldLayout>
+        );
+      }}
+    </Field>
+  );
+}