@fpkit/acss 3.7.0 → 3.8.0

package/libs/index.d.cts

@@ -176,6 +176,361 @@ type AlertProps = {
 } & Omit<React$1.HTMLAttributes<HTMLDivElement>, "title" | "children">;
 declare const Alert: React$1.FC<AlertProps>;
 
+/**
+ * Size variants for checkbox component using t-shirt sizing.
+ *
+ * @remarks
+ * Size affects both the checkbox visual size and label font size:
+ * - sm: 1rem checkbox, 0.875rem label (16px / 14px)
+ * - md: 1.25rem checkbox, 1rem label (20px / 16px)
+ * - lg: 1.5rem checkbox, 1.125rem label (24px / 18px)
+ */
+type CheckboxSize = "sm" | "md" | "lg";
+/**
+ * Color variants for checkbox component.
+ * All variants meet WCAG 2.1 AA contrast requirements (4.5:1 minimum).
+ *
+ * @remarks
+ * Color variants:
+ * - primary: Blue (#2563eb) - 4.68:1 contrast
+ * - secondary: Gray (#4b5563) - 7.56:1 contrast
+ * - error: Red (#dc2626) - 5.14:1 contrast
+ * - success: Green (#16a34a) - 4.54:1 contrast
+ */
+type CheckboxColor = "primary" | "secondary" | "error" | "success";
+/**
+ * Label positioning relative to the checkbox.
+ *
+ * @remarks
+ * - left: Label appears before the checkbox
+ * - right: Label appears after the checkbox (default)
+ */
+type CheckboxLabelPosition = "left" | "right";
+/**
+ * Props for the Checkbox component.
+ *
+ * @remarks
+ * Checkbox supports both controlled and uncontrolled modes:
+ * - Controlled: Pass `checked` prop and `onChange` handler
+ * - Uncontrolled: Pass `defaultChecked` prop only
+ *
+ * For AI assistants: This component implements WCAG 2.1 AA accessibility
+ * with proper ARIA attributes, keyboard navigation, and focus management.
+ */
+interface CheckboxProps extends Omit<React$1.ComponentPropsWithoutRef<"input">, "type" | "size" | "className"> {
+    /**
+     * Unique identifier for the checkbox input.
+     *
+     * @remarks
+     * Required for proper label association and ARIA attribute linking.
+     * Used to generate IDs for description and error messages.
+     */
+    id: string;
+    /**
+     * Label text content displayed next to the checkbox.
+     *
+     * @remarks
+     * Alternative to `children` prop. Rendered as text content.
+     * Automatically associates with input via htmlFor.
+     */
+    label?: React$1.ReactNode;
+    /**
+     * Child content displayed as the label.
+     *
+     * @remarks
+     * Alternative to `label` prop. Allows for more complex label content.
+     * Takes precedence over `label` prop if both are provided.
+     */
+    children?: React$1.ReactNode;
+    /**
+     * Size variant of the checkbox.
+     *
+     * @default "md"
+     *
+     * @remarks
+     * Affects both checkbox size and label font size.
+     * All sizes maintain proper touch target size (44x44px minimum).
+     */
+    size?: CheckboxSize;
+    /**
+     * Color variant of the checkbox when checked.
+     *
+     * @default "primary"
+     *
+     * @remarks
+     * All color variants meet WCAG 2.1 AA contrast requirements.
+     * Use semantic colors (error, success) for validation states.
+     */
+    color?: CheckboxColor;
+    /**
+     * Position of the label relative to the checkbox.
+     *
+     * @default "right"
+     *
+     * @remarks
+     * - "left": Label before checkbox (useful for RTL layouts)
+     * - "right": Label after checkbox (standard pattern)
+     */
+    labelPosition?: CheckboxLabelPosition;
+    /**
+     * Helper text displayed below the checkbox.
+     *
+     * @remarks
+     * Provides additional context or instructions.
+     * Linked to input via aria-describedby for screen readers.
+     * Automatically generates ID: `${id}-description`.
+     */
+    description?: string;
+    /**
+     * Error message displayed when validation fails.
+     *
+     * @remarks
+     * Displayed below the checkbox in error color.
+     * Linked to input via aria-errormessage when validationState="invalid".
+     * Automatically generates ID: `${id}-error`.
+     */
+    errorMessage?: string;
+    /**
+     * Validation state of the checkbox.
+     *
+     * @default "none"
+     *
+     * @remarks
+     * - "valid": Checkbox passes validation
+     * - "invalid": Checkbox fails validation (sets aria-invalid)
+     * - "none": No validation applied
+     */
+    validationState?: "valid" | "invalid" | "none";
+    /**
+     * Checked state for controlled mode.
+     *
+     * @remarks
+     * When provided, component operates in controlled mode.
+     * Must be used with onChange handler to update state.
+     * Do not combine with defaultChecked.
+     */
+    checked?: boolean;
+    /**
+     * Default checked state for uncontrolled mode.
+     *
+     * @remarks
+     * When provided without `checked` prop, component operates in uncontrolled mode.
+     * Browser manages state internally.
+     * Do not combine with checked.
+     */
+    defaultChecked?: boolean;
+    /**
+     * Indeterminate state for partially selected groups.
+     *
+     * @default false
+     *
+     * @remarks
+     * Common for "select all" checkboxes where some but not all items are selected.
+     * Cannot be set via HTML - requires JavaScript.
+     * Visually displays a dash instead of a checkmark.
+     */
+    indeterminate?: boolean;
+    /**
+     * Whether the checkbox is disabled.
+     *
+     * @remarks
+     * Uses aria-disabled pattern to maintain keyboard focusability.
+     * Prevents all interactions while keeping element in tab order.
+     * Essential for screen reader users to discover disabled controls.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the checkbox is required for form submission.
+     *
+     * @default false
+     *
+     * @remarks
+     * Sets aria-required attribute for screen readers.
+     * Displays visual required indicator (asterisk).
+     * Does NOT prevent form submission - use validation instead.
+     */
+    required?: boolean;
+    /**
+     * Name attribute for form submission.
+     *
+     * @remarks
+     * Used when checkbox is part of a form.
+     * Multiple checkboxes can share the same name for checkbox groups.
+     */
+    name?: string;
+    /**
+     * Value attribute for form submission.
+     *
+     * @remarks
+     * Submitted with form when checkbox is checked.
+     * Defaults to "on" if not specified.
+     */
+    value?: string;
+    /**
+     * CSS class names to apply to the wrapper element.
+     *
+     * @remarks
+     * Applied to the outermost div wrapper.
+     * Merged with disabled class from useDisabledState hook.
+     */
+    classes?: string;
+    /**
+     * Inline styles to apply to the wrapper element.
+     *
+     * @remarks
+     * Use CSS custom properties for theming:
+     * - --checkbox-size: Custom checkbox size
+     * - --checkbox-checked-bg: Checked background color
+     * - --checkbox-border: Border style
+     * See STYLES.mdx for complete variable reference.
+     */
+    styles?: React$1.CSSProperties;
+    /**
+     * Event handler fired when checkbox state changes.
+     *
+     * @param event - Change event from the input element
+     *
+     * @remarks
+     * Required when using controlled mode (with `checked` prop).
+     * Prevented when checkbox is disabled (via useDisabledState hook).
+     */
+    onChange?: React$1.ChangeEventHandler<HTMLInputElement>;
+    /**
+     * Event handler fired when checkbox loses focus.
+     *
+     * @param event - Focus event from the input element
+     */
+    onBlur?: React$1.FocusEventHandler<HTMLInputElement>;
+    /**
+     * Event handler fired when checkbox gains focus.
+     *
+     * @param event - Focus event from the input element
+     *
+     * @remarks
+     * Still fires when checkbox is disabled (for accessibility).
+     * useDisabledState hook allows focus events on disabled elements.
+     */
+    onFocus?: React$1.FocusEventHandler<HTMLInputElement>;
+}
+/**
+ * Checkbox - Accessible checkbox input with size and color variants.
+ *
+ * A fully accessible checkbox component that supports controlled and uncontrolled modes,
+ * indeterminate state, validation, and comprehensive ARIA attributes for screen readers.
+ *
+ * ## Key Features
+ *
+ * - **Accessible**: WCAG 2.1 AA compliant with proper ARIA attributes
+ * - **Flexible**: Controlled and uncontrolled modes
+ * - **Indeterminate**: Supports three-state checkboxes
+ * - **Validation**: Built-in error message and validation state support
+ * - **Customizable**: Size and color variants, plus CSS custom properties
+ * - **Keyboard**: Full keyboard navigation (Tab, Space)
+ * - **Type-Safe**: Full TypeScript support with comprehensive JSDoc
+ *
+ * ## Accessibility Considerations
+ *
+ * ### WCAG 2.1 AA Compliance
+ *
+ * - **3.2.2 On Input (Level A)**: onChange events don't cause unexpected context changes
+ * - **4.1.2 Name, Role, Value (Level A)**: Proper ARIA attributes communicate state
+ * - **1.4.3 Contrast (Minimum) (Level AA)**: All color variants meet 4.5:1 contrast
+ * - **2.4.7 Focus Visible (Level AA)**: Clear focus indicators on keyboard navigation
+ *
+ * ### Best Practices
+ *
+ * 1. **Always provide labels**: Use `label` or `children` prop for accessible name
+ * 2. **Use semantic colors**: error variant for validation failures
+ * 3. **Provide descriptions**: Use `description` prop for additional context
+ * 4. **Group related checkboxes**: Use fieldset/legend for checkbox groups
+ * 5. **Don't mix modes**: Use either controlled or uncontrolled, not both
+ *
+ * ## Usage Examples
+ *
+ * @example
+ * // Basic checkbox
+ * <Checkbox id="terms" label="I accept the terms and conditions" />
+ *
+ * @example
+ * // Controlled checkbox
+ * const [checked, setChecked] = useState(false);
+ * <Checkbox
+ *   id="newsletter"
+ *   label="Subscribe to newsletter"
+ *   checked={checked}
+ *   onChange={(e) => setChecked(e.target.checked)}
+ * />
+ *
+ * @example
+ * // Checkbox with validation error
+ * <Checkbox
+ *   id="agree"
+ *   label="You must agree to continue"
+ *   required
+ *   validationState="invalid"
+ *   errorMessage="Please accept the terms to continue"
+ * />
+ *
+ * @example
+ * // Checkbox with description
+ * <Checkbox
+ *   id="notifications"
+ *   label="Enable notifications"
+ *   description="Receive email notifications about important updates"
+ * />
+ *
+ * @example
+ * // Indeterminate checkbox (select all pattern)
+ * const [selectedItems, setSelectedItems] = useState([]);
+ * const allSelected = selectedItems.length === totalItems;
+ * const someSelected = selectedItems.length > 0 && !allSelected;
+ *
+ * <Checkbox
+ *   id="select-all"
+ *   label="Select all"
+ *   checked={allSelected}
+ *   indeterminate={someSelected}
+ *   onChange={(e) => {
+ *     if (e.target.checked) {
+ *       setSelectedItems(allItemIds);
+ *     } else {
+ *       setSelectedItems([]);
+ *     }
+ *   }}
+ * />
+ *
+ * @example
+ * // Size and color variants
+ * <Checkbox id="sm" label="Small primary" size="sm" color="primary" />
+ * <Checkbox id="md" label="Medium secondary" size="md" color="secondary" />
+ * <Checkbox id="lg" label="Large success" size="lg" color="success" />
+ *
+ * @example
+ * // Label positioning
+ * <Checkbox id="left" label="Label on left" labelPosition="left" />
+ * <Checkbox id="right" label="Label on right" labelPosition="right" />
+ *
+ * @example
+ * // Custom styling with CSS variables
+ * <Checkbox
+ *   id="custom"
+ *   label="Custom styled"
+ *   styles={{
+ *     "--checkbox-size": "2rem",
+ *     "--checkbox-checked-bg": "#7c3aed",
+ *     "--checkbox-radius": "0.5rem",
+ *   }}
+ * />
+ *
+ * @param {CheckboxProps} props - Component props
+ * @returns {React.ReactElement} Checkbox component
+ *
+ * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/on-input.html WCAG 3.2.2 On Input}
+ * @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/ARIA/apg/patterns/checkbox/ ARIA Checkbox Pattern}
+ */
+declare const Checkbox: React$1.ForwardRefExoticComponent<CheckboxProps & React$1.RefAttributes<HTMLInputElement>>;
+
 /**
  * Props for the Img component.
  *
@@ -2546,4 +2901,4 @@ type FPComponent = {
  */
 declare const FP: FPComponent;
 
-export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, Box, BoxProps, Caption, Cluster, ClusterProps, Col, ColProps, ComponentProps$1 as ComponentProps, Details, FP, Flex, FlexAlign, FlexAlignContent, FlexAlignSelf, FlexContainerElement, FlexDirection, FlexGap, FlexItemElement, FlexItemProps, FlexJustify, FlexProps, FlexSpacerProps, FlexVariant, FlexWrap, Footer, GridWithItem as Grid, GridItem, GridItemProps, GridProps, Header, Img, ImgProps, Landmarks, Main, ResponsiveFlexProps, Row, RowProps, Section, Stack, StackProps, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };
+export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, Box, BoxProps, Caption, Checkbox, CheckboxColor, CheckboxLabelPosition, CheckboxProps, CheckboxSize, Cluster, ClusterProps, Col, ColProps, ComponentProps$1 as ComponentProps, Details, FP, Flex, FlexAlign, FlexAlignContent, FlexAlignSelf, FlexContainerElement, FlexDirection, FlexGap, FlexItemElement, FlexItemProps, FlexJustify, FlexProps, FlexSpacerProps, FlexVariant, FlexWrap, Footer, GridWithItem as Grid, GridItem, GridItemProps, GridProps, Header, Img, ImgProps, Landmarks, Main, ResponsiveFlexProps, Row, RowProps, Section, Stack, StackProps, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };