@fpkit/acss 3.7.0 → 3.9.0

package/src/components/form/checkbox.scss

@@ -0,0 +1,129 @@
+/**
+ * Checkbox Wrapper Component Styles
+ *
+ * Modern CSS architecture using :has() selector with ARIA attributes.
+ * No JavaScript class management required - ARIA attributes drive both
+ * accessibility AND styling.
+ *
+ * CSS Custom Properties:
+ * - --checkbox-gap: Space between checkbox and label (default: 0.5rem)
+ * - --checkbox-disabled-opacity: Opacity for disabled state (default: 0.6)
+ * - --checkbox-disabled-color: Label color when disabled (default: #6b7280)
+ * - --checkbox-label-fs: Label font size (default: 1rem)
+ * - --checkbox-label-lh: Label line height (default: 1.5)
+ * - --color-required: Required indicator color (default: #dc2626)
+ * - --checkbox-focus-ring-color: Focus ring color (default: #2563eb)
+ * - --checkbox-focus-ring-width: Focus ring width (default: 0.125rem)
+ * - --checkbox-focus-ring-offset: Focus ring offset (default: 0.125rem)
+ * - --checkbox-hover-label-color: Label color on hover (default: inherit)
+ * - --checkbox-error-label-color: Label color when invalid (default: #dc2626)
+ * - --checkbox-valid-label-color: Label color when valid (default: #16a34a)
+ * - --checkbox-focus-radius: Focus outline border radius (default: 0.125rem)
+ *
+ * WCAG 2.1 AA Compliance:
+ * - 2.4.7 Focus Visible: Focus-visible indicators with sufficient contrast
+ * - 2.3.3 Animation from Interactions: Respects prefers-reduced-motion
+ * - 3.3.1 Error Identification: Visual error states with color + text
+ * - 4.1.2 Name, Role, Value: ARIA attributes for assistive technologies
+ * - 1.4.13 Content on Hover or Focus: Hover states for visual feedback
+ */
+
+// Checkbox wrapper styling using modern :has() selector
+div:has(> input[type="checkbox"]) {
+  display: flex;
+  align-items: center;
+  gap: var(--checkbox-gap, 0.5rem);
+  position: relative;
+
+  // Ensure checkbox doesn't overlap label
+  > input[type="checkbox"] {
+    flex-shrink: 0; // Prevent checkbox from shrinking
+    order: -1; // Ensure checkbox appears first
+  }
+
+  // Hover state (only when not disabled) - WCAG 1.4.13 Content on Hover
+  &:not(:has(> input[aria-disabled="true"])):hover {
+    .checkbox-label {
+      color: var(--checkbox-hover-label-color, inherit);
+    }
+  }
+
+  // Focus-visible state for keyboard navigation - WCAG 2.4.7 Focus Visible
+  // Using :focus-visible to only show focus ring for keyboard users
+  &:has(> input:focus-visible) {
+    .checkbox-label {
+      outline: var(--checkbox-focus-ring-width, 0.125rem) solid
+        var(--checkbox-focus-ring-color, #2563eb);
+      outline-offset: var(--checkbox-focus-ring-offset, 0.125rem);
+      border-radius: var(--checkbox-focus-radius, 0.125rem);
+    }
+  }
+
+  // Disabled state styling using aria-disabled attribute selector
+  // WCAG 4.1.2: aria-disabled remains focusable for screen readers
+  &:has(> input[aria-disabled="true"]) {
+    opacity: var(--checkbox-disabled-opacity, 0.6);
+    cursor: not-allowed;
+
+    .checkbox-label {
+      color: var(--checkbox-disabled-color, #6b7280);
+      cursor: not-allowed;
+    }
+  }
+
+  // Invalid state styling - WCAG 3.3.1 Error Identification
+  // Color alone is not sufficient - error message text must also be provided
+  &:has(> input[aria-invalid="true"]) {
+    .checkbox-label {
+      color: var(--checkbox-error-label-color, #dc2626);
+    }
+  }
+
+  // Valid state styling (when checked and explicitly marked valid)
+  &:has(> input[aria-invalid="false"]:checked) {
+    .checkbox-label {
+      color: var(--checkbox-valid-label-color, #16a34a);
+    }
+  }
+}
+
+// Checkbox label styling
+.checkbox-label {
+  cursor: pointer;
+  font-size: var(--checkbox-label-fs, 1rem);
+  line-height: var(--checkbox-label-lh, 1.5);
+  user-select: none;
+  margin: 0;
+  flex: 1; // Allow label to take remaining space
+  min-width: 0; // Prevent flex item from overflowing
+  transition: color 0.2s ease-in-out;
+
+  // Respect user's motion preferences - WCAG 2.3.3 Animation from Interactions
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+
+  .checkbox-required {
+    color: var(--color-required, #dc2626);
+    font-weight: 600;
+    margin-inline-start: 0.125rem;
+  }
+}
+
+// Checkbox input element
+.checkbox-input {
+  // High contrast mode support (Windows High Contrast Mode)
+  // forced-color-adjust: auto respects user's color scheme
+  @media (forced-colors: active) {
+    forced-color-adjust: auto;
+  }
+}
+
+// Optional: Container query support for responsive layouts
+// Stacks checkbox and label vertically on small containers
+@container (max-width: 400px) {
+  div:has(> input[type="checkbox"]) {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+}

package/src/components/form/checkbox.tsx

@@ -0,0 +1,302 @@
+import React from "react";
+import { Input, type InputProps } from "./inputs";
+
+/**
+ * Props for the Checkbox component
+ *
+ * A simplified, checkbox-specific interface that wraps the Input component.
+ * Provides a boolean onChange API and automatic label association.
+ *
+ * @example
+ * ```tsx
+ * // Controlled mode
+ * <Checkbox
+ *   id="terms"
+ *   label="I accept the terms"
+ *   checked={accepted}
+ *   onChange={setAccepted}
+ *   required
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled mode with default
+ * <Checkbox
+ *   id="newsletter"
+ *   label="Subscribe to newsletter"
+ *   defaultChecked={true}
+ * />
+ * ```
+ */
+export interface CheckboxProps extends Omit<
+  InputProps,
+  'type' | 'value' | 'onChange' | 'defaultValue' | 'placeholder'
+> {
+  /**
+   * Unique identifier for the checkbox input.
+   * Required for proper label association via htmlFor attribute.
+   *
+   * @required
+   * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html|WCAG 4.1.2 Name, Role, Value}
+   */
+  id: string;
+
+  /**
+   * Label text or React node displayed next to the checkbox.
+   * Automatically associated with the checkbox via htmlFor.
+   *
+   * @required
+   * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html|WCAG 3.3.2 Labels or Instructions}
+   */
+  label: React.ReactNode;
+
+  /**
+   * Controlled mode: Current checked state.
+   * When provided, component becomes controlled and requires onChange handler.
+   *
+   * @example
+   * ```tsx
+   * const [checked, setChecked] = useState(false);
+   * <Checkbox id="opt" label="Option" checked={checked} onChange={setChecked} />
+   * ```
+   */
+  checked?: boolean;
+
+  /**
+   * Uncontrolled mode: Initial checked state.
+   * Use this for forms where React doesn't need to track the checkbox state.
+   *
+   * @default false
+   * @example
+   * ```tsx
+   * <Checkbox id="opt" label="Option" defaultChecked={true} />
+   * ```
+   */
+  defaultChecked?: boolean;
+
+  /**
+   * Form submission value when checkbox is checked.
+   * This is the value submitted with the form when the checkbox is checked.
+   *
+   * @default "on"
+   */
+  value?: string;
+
+  /**
+   * Change handler with simplified boolean API.
+   * Receives true when checked, false when unchecked.
+   *
+   * @param checked - The new checked state
+   * @example
+   * ```tsx
+   * <Checkbox
+   *   id="opt"
+   *   label="Option"
+   *   onChange={(checked) => console.log('Checked:', checked)}
+   * />
+   * ```
+   */
+  onChange?: (checked: boolean) => void;
+
+  /**
+   * Optional custom CSS classes for the wrapper div.
+   * Applied alongside automatic checkbox wrapper styling.
+   */
+  classes?: string;
+
+  /**
+   * Optional custom CSS classes for the input element.
+   *
+   * @default "checkbox-input"
+   */
+  inputClasses?: string;
+
+  /**
+   * CSS custom properties for theming.
+   *
+   * Available variables:
+   * - --checkbox-gap: Space between checkbox and label (default: 0.5rem)
+   * - --checkbox-disabled-opacity: Opacity for disabled state (default: 0.6)
+   * - --checkbox-disabled-color: Label color when disabled (default: #6b7280)
+   * - --checkbox-label-fs: Label font size (default: 1rem)
+   * - --checkbox-label-lh: Label line height (default: 1.5)
+   * - --color-required: Required indicator color (default: #dc2626)
+   * - --checkbox-focus-ring-color: Focus ring color (default: #2563eb)
+   * - --checkbox-focus-ring-width: Focus ring width (default: 0.125rem)
+   * - --checkbox-focus-ring-offset: Focus ring offset (default: 0.125rem)
+   * - --checkbox-hover-label-color: Label color on hover
+   * - --checkbox-error-label-color: Label color when invalid (default: #dc2626)
+   * - --checkbox-valid-label-color: Label color when valid (default: #16a34a)
+   *
+   * @example
+   * ```tsx
+   * <Checkbox
+   *   id="custom"
+   *   label="Custom styled"
+   *   styles={{
+   *     '--checkbox-gap': '1rem',
+   *     '--checkbox-focus-ring-color': '#ff0000'
+   *   }}
+   * />
+   * ```
+   */
+  styles?: React.CSSProperties;
+}
+
+/**
+ * Checkbox - Accessible checkbox input with automatic label association
+ *
+ * A thin wrapper around the Input component that provides a checkbox-specific API
+ * with simplified boolean onChange and automatic label rendering. Leverages all
+ * validation, disabled state, and ARIA logic from the base Input component.
+ *
+ * **Key Features:**
+ * - ✅ Boolean onChange API (`onChange={(checked) => ...}`)
+ * - ✅ Automatic label association via htmlFor
+ * - ✅ WCAG 2.1 AA compliant (uses aria-disabled pattern)
+ * - ✅ Supports both controlled and uncontrolled modes
+ * - ✅ Required indicator with asterisk
+ * - ✅ Validation states (invalid, valid, none)
+ * - ✅ Error messages and hint text via Input component
+ * - ✅ Customizable via CSS custom properties
+ * - ✅ Keyboard accessible (Space to toggle)
+ * - ✅ Focus-visible indicators
+ * - ✅ High contrast mode support
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic checkbox
+ * <Checkbox id="terms" label="I accept the terms and conditions" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled checkbox with validation
+ * const [agreed, setAgreed] = useState(false);
+ * <Checkbox
+ *   id="terms"
+ *   label="I accept the terms"
+ *   checked={agreed}
+ *   onChange={setAgreed}
+ *   required
+ *   validationState={agreed ? "valid" : "invalid"}
+ *   errorMessage={!agreed ? "You must accept the terms" : undefined}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled checkbox
+ * <Checkbox
+ *   id="disabled"
+ *   label="Disabled option"
+ *   disabled
+ *   defaultChecked
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling
+ * <Checkbox
+ *   id="custom"
+ *   label="Large checkbox"
+ *   styles={{ '--checkbox-gap': '1rem' }}
+ * />
+ * ```
+ *
+ * @param {CheckboxProps} props - Component props
+ * @param {React.Ref<HTMLInputElement>} ref - Forwarded ref to the input element
+ * @returns {JSX.Element} Checkbox wrapper with input and label
+ *
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html|WCAG 4.1.2 Name, Role, Value}
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html|WCAG 2.4.7 Focus Visible}
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html|WCAG 3.3.1 Error Identification}
+ */
+export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
+  ({
+    id, label, checked, defaultChecked, value = "on",
+    onChange, classes, inputClasses, styles,
+    name, disabled, required, validationState,
+    errorMessage, hintText, onBlur, onFocus, autoFocus,
+    ...props
+  }, ref) => {
+
+    // Convert boolean onChange to native event handler
+    // Memoized to prevent unnecessary re-renders of child components
+    const handleChange = React.useCallback(
+      (e: React.ChangeEvent<HTMLInputElement>) => {
+        onChange?.(e.target.checked);
+      },
+      [onChange]
+    );
+
+    // Controlled vs uncontrolled mode
+    const isControlled = checked !== undefined;
+    const checkedProp = isControlled ? { checked } : {};
+    const defaultCheckedProp = !isControlled && defaultChecked !== undefined
+      ? { defaultChecked }
+      : {};
+
+    // Dev-only validation: Warn if switching between controlled/uncontrolled
+    // This helps catch common React bugs where state management changes mid-lifecycle
+    const wasControlledRef = React.useRef(isControlled);
+
+    React.useEffect(() => {
+      if (process.env.NODE_ENV === 'development') {
+        if (wasControlledRef.current !== isControlled) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `Checkbox with id="${id}" is changing from ${
+              wasControlledRef.current ? 'controlled' : 'uncontrolled'
+            } to ${
+              isControlled ? 'controlled' : 'uncontrolled'
+            }. This is likely a bug. ` +
+            `Decide between using "checked" (controlled) or "defaultChecked" (uncontrolled) and stick with it.`
+          );
+        }
+        wasControlledRef.current = isControlled;
+      }
+    }, [isControlled, id]);
+
+    // Note: No need to manage disabled class - CSS uses :has() selector with aria-disabled
+    // The Input component handles aria-disabled automatically via useDisabledState hook
+    return (
+      <div className={classes} style={styles}>
+        <Input
+          ref={ref}
+          type="checkbox"
+          id={id}
+          name={name}
+          value={value}
+          {...checkedProp}
+          {...defaultCheckedProp}
+          classes={inputClasses || "checkbox-input"}
+          disabled={disabled}
+          required={required}
+          validationState={validationState}
+          errorMessage={errorMessage}
+          hintText={hintText}
+          onChange={handleChange}
+          onBlur={onBlur}
+          onFocus={onFocus}
+          autoFocus={autoFocus}
+          {...props}
+        />
+        <label htmlFor={id} className="checkbox-label">
+          {label}
+          {required && (
+            <span className="checkbox-required" aria-label="required">
+              {" *"}
+            </span>
+          )}
+        </label>
+      </div>
+    );
+  }
+);
+
+Checkbox.displayName = "Checkbox";
+export default Checkbox;

package/src/components/form/form.scss

@@ -1,3 +1,6 @@
+// Import checkbox wrapper component styles
+@use "./checkbox";
+
 :root {
   --input-border-color: gray;
   --input-appearance: none;
@@ -26,6 +29,26 @@
 
   --form-direction: column;
   --select-arrow: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20'><polyline points='6,9 10,13 14,9' stroke='%23000000' stroke-width='1.5' fill='none' /></svg>");
+
+  /* ==========================================================================
+     Size Tokens
+     ========================================================================== */
+
+  --checkbox-size-sm: 1rem; /* 16px */
+  --checkbox-size-md: 1.25rem; /* 20px */
+  --checkbox-size-lg: 1.5rem; /* 24px */
+
+  /* ==========================================================================
+     Base Properties
+     ========================================================================== */
+
+  --checkbox-size: var(--checkbox-size-md);
+  --checkbox-bg: #ffffff;
+  --checkbox-border: 0.125rem solid #6b7280; /* 2px border */
+  --checkbox-border-color: #6b7280; /* Gray 500 */
+  --checkbox-radius: 0.25rem; /* 4px */
+  --checkbox-cursor: pointer;
+  --checkbox-transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
 }
 
 form {
@@ -43,9 +66,7 @@ form {
   }
 }
 
-input[type]:not([type='checkbox'], [type='radio']),
-textarea,
-select {
+input {
   -webkit-appearance: var(--input-appearance);
   -moz-appearance: var(--input-appearance);
   appearance: var(--input-appearance);
@@ -57,37 +78,55 @@ select {
   border-radius: var(--input-radius);
   background-color: var(--input-bg, #fff);
 
+  &:focus-visible,
+  &:focus {
+    outline: var(--input-focus-outline);
+    outline-offset: var(--input-focus-outline-offset);
+  }
+
+  &[aria-disabled="true"],
+  &:disabled {
+    --input-border-color: lightgray;
+    background-color: var(--input-disabled-bg);
+    opacity: var(--input-disabled-opacity);
+    cursor: var(--input-disabled-cursor);
+    text-transform: capitalize;
+    text-decoration: line-through;
+  }
+}
+
+input[type]:not([type="checkbox"], [type="radio"]),
+textarea,
+select {
   &::placeholder {
     color: var(--placeholder-color);
     font-style: var(--placeholder-style);
     font-size: var(--placeholder-fs);
     text-transform: capitalize;
   }
-
-  &:focus-visible, &:focus {
-    outline: var(--input-focus-outline);
-    outline-offset: var(--input-focus-outline-offset);
-  }
-
-
-  &[aria-required='true'] {
+  &[aria-required="true"] {
     &::placeholder {
       color: var(--color-required, var(--placeholder-color));
       font-weight: 600;
       &::after {
-        content: '* ';
+        content: "* ";
       }
     }
   }
+}
 
-  &[aria-disabled='true'],
-  &:disabled {
-    --input-border-color: lightgray;
-    background-color: var(--input-disabled-bg);
-    opacity: var(--input-disabled-opacity);
-    cursor: var(--input-disabled-cursor);
-    text-transform: capitalize;
-    text-decoration: line-through;
+input[type="checkbox"] {
+  opacity: 1;
+  width: var(--checkbox-size);
+  height: var(--checkbox-size);
+  margin: 0;
+  cursor: var(--checkbox-cursor);
+  flex-shrink: 0; // Prevent checkbox from shrinking in flex layout
+
+  &:checked {
+    background-color: var(--checkbox-bg, red);
+    outline: rebeccapurple solid 2px;
+    background: #dbeafe;
   }
 }
 

package/src/components/form/form.types.ts

@@ -376,3 +376,9 @@ export interface SelectProps extends Omit<React.ComponentPropsWithoutRef<'select
    */
   children?: React.ReactNode
 }
+
+/**
+ * Checkbox component props
+ * Re-exported from checkbox.tsx for convenience
+ */
+export type { CheckboxProps } from './checkbox'