@fpkit/acss 3.8.0 → 4.0.0

package/libs/index.d.cts

@@ -5,6 +5,8 @@ import { I as IconProps } from './icons-df8e744f.js';
 export { a as Icon, b as IconProps } from './icons-df8e744f.js';
 export { default as Field, FieldProps } from './components/form/fields.cjs';
 export { default as Input } from './components/form/inputs.cjs';
+import { I as InputProps } from './form.types-d25ebfac.js';
+export { T as TextareaProps } from './form.types-d25ebfac.js';
 export { _ as Link, L as LinkProps, _ as To } from './link-59ad884f.js';
 export { default as List } from './components/list/list.cjs';
 export { Modal, ModalProps } from './components/modal.cjs';
@@ -18,7 +20,6 @@ export { default as Text, TextProps } from './components/text/text.cjs';
 export { b as Heading, H as HeadingLevel, T as Title, a as TitleProps } from './heading-81eef89a.js';
 export { default as Textarea } from './components/form/textarea.cjs';
 export { default as Breadcrumb, BreadcrumbProps, CustomRoute, useBreadcrumbSegments } from './components/breadcrumbs/breadcrumb.cjs';
-export { I as InputProps, T as TextareaProps } from './form.types-d25ebfac.js';
 export { L as ListItemProps, a as ListProps } from './list.types-d26de310.js';
 
 /**
@@ -177,357 +178,206 @@ type AlertProps = {
 declare const Alert: React$1.FC<AlertProps>;
 
 /**
- * Size variants for checkbox component using t-shirt sizing.
+ * Props for the Checkbox component
  *
- * @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.
+ * A simplified, checkbox-specific interface that wraps the Input component.
+ * Provides a boolean onChange API and automatic label association.
  *
- * @remarks
- * Checkbox supports both controlled and uncontrolled modes:
- * - Controlled: Pass `checked` prop and `onChange` handler
- * - Uncontrolled: Pass `defaultChecked` prop only
+ * @example
+ * ```tsx
+ * // Controlled mode
+ * <Checkbox
+ *   id="terms"
+ *   label="I accept the terms"
+ *   checked={accepted}
+ *   onChange={setAccepted}
+ *   required
+ * />
+ * ```
  *
- * For AI assistants: This component implements WCAG 2.1 AA accessibility
- * with proper ARIA attributes, keyboard navigation, and focus management.
+ * @example
+ * ```tsx
+ * // Uncontrolled mode with default
+ * <Checkbox
+ *   id="newsletter"
+ *   label="Subscribe to newsletter"
+ *   defaultChecked={true}
+ * />
+ * ```
  */
-interface CheckboxProps extends Omit<React$1.ComponentPropsWithoutRef<"input">, "type" | "size" | "className"> {
+interface CheckboxProps extends Omit<InputProps, 'type' | 'value' | 'onChange' | 'defaultValue' | 'placeholder'> {
     /**
      * Unique identifier for the checkbox input.
+     * Required for proper label association via htmlFor attribute.
      *
-     * @remarks
-     * Required for proper label association and ARIA attribute linking.
-     * Used to generate IDs for description and error messages.
+     * @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 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"
+     * Label text or React node displayed next to the checkbox.
+     * Automatically associated with the checkbox via htmlFor.
      *
-     * @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
+     * @required
+     * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions.html|WCAG 3.3.2 Labels or Instructions}
      */
-    validationState?: "valid" | "invalid" | "none";
+    label: React$1.ReactNode;
     /**
-     * Checked state for controlled mode.
+     * Controlled mode: Current checked state.
+     * When provided, component becomes controlled and requires onChange handler.
      *
-     * @remarks
-     * When provided, component operates in controlled mode.
-     * Must be used with onChange handler to update state.
-     * Do not combine with defaultChecked.
+     * @example
+     * ```tsx
+     * const [checked, setChecked] = useState(false);
+     * <Checkbox id="opt" label="Option" checked={checked} onChange={setChecked} />
+     * ```
      */
     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.
+     * Uncontrolled mode: Initial checked state.
+     * Use this for forms where React doesn't need to track the checkbox state.
      *
      * @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.
+     * @example
+     * ```tsx
+     * <Checkbox id="opt" label="Option" defaultChecked={true} />
+     * ```
      */
-    name?: string;
+    defaultChecked?: boolean;
     /**
-     * Value attribute for form submission.
+     * Form submission value when checkbox is checked.
+     * This is the value submitted with the form when the checkbox is checked.
      *
-     * @remarks
-     * Submitted with form when checkbox is checked.
-     * Defaults to "on" if not specified.
+     * @default "on"
      */
     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.
+     * Change handler with simplified boolean API.
+     * Receives true when checked, false when unchecked.
      *
-     * @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.
+     * @param checked - The new checked state
+     * @example
+     * ```tsx
+     * <Checkbox
+     *   id="opt"
+     *   label="Option"
+     *   onChange={(checked) => console.log('Checked:', checked)}
+     * />
+     * ```
      */
-    styles?: React$1.CSSProperties;
+    onChange?: (checked: boolean) => void;
     /**
-     * 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).
+     * Optional custom CSS classes for the wrapper div.
+     * Applied alongside automatic checkbox wrapper styling.
      */
-    onChange?: React$1.ChangeEventHandler<HTMLInputElement>;
+    classes?: string;
     /**
-     * Event handler fired when checkbox loses focus.
+     * Optional custom CSS classes for the input element.
      *
-     * @param event - Focus event from the input element
+     * @default "checkbox-input"
      */
-    onBlur?: React$1.FocusEventHandler<HTMLInputElement>;
+    inputClasses?: string;
     /**
-     * Event handler fired when checkbox gains focus.
+     * CSS custom properties for theming.
      *
-     * @param event - Focus event from the input element
+     * 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)
      *
-     * @remarks
-     * Still fires when checkbox is disabled (for accessibility).
-     * useDisabledState hook allows focus events on disabled elements.
+     * @example
+     * ```tsx
+     * <Checkbox
+     *   id="custom"
+     *   label="Custom styled"
+     *   styles={{
+     *     '--checkbox-gap': '1rem',
+     *     '--checkbox-focus-ring-color': '#ff0000'
+     *   }}
+     * />
+     * ```
      */
-    onFocus?: React$1.FocusEventHandler<HTMLInputElement>;
+    styles?: React$1.CSSProperties;
 }
 /**
- * Checkbox - Accessible checkbox input with size and color variants.
+ * Checkbox - Accessible checkbox input with automatic label association
  *
- * A fully accessible checkbox component that supports controlled and uncontrolled modes,
- * indeterminate state, validation, and comprehensive ARIA attributes for screen readers.
+ * 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
- *
- * - **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
+ * **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
- * // 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
+ * ```tsx
+ * // Controlled checkbox with validation
+ * const [agreed, setAgreed] = useState(false);
  * <Checkbox
- *   id="agree"
- *   label="You must agree to continue"
+ *   id="terms"
+ *   label="I accept the terms"
+ *   checked={agreed}
+ *   onChange={setAgreed}
  *   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"
+ *   validationState={agreed ? "valid" : "invalid"}
+ *   errorMessage={!agreed ? "You must accept the terms" : undefined}
  * />
+ * ```
  *
  * @example
- * // Indeterminate checkbox (select all pattern)
- * const [selectedItems, setSelectedItems] = useState([]);
- * const allSelected = selectedItems.length === totalItems;
- * const someSelected = selectedItems.length > 0 && !allSelected;
- *
+ * ```tsx
+ * // Disabled checkbox
  * <Checkbox
- *   id="select-all"
- *   label="Select all"
- *   checked={allSelected}
- *   indeterminate={someSelected}
- *   onChange={(e) => {
- *     if (e.target.checked) {
- *       setSelectedItems(allItemIds);
- *     } else {
- *       setSelectedItems([]);
- *     }
- *   }}
+ *   id="disabled"
+ *   label="Disabled option"
+ *   disabled
+ *   defaultChecked
  * />
+ * ```
  *
  * @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
+ * ```tsx
+ * // Custom styling
  * <Checkbox
  *   id="custom"
- *   label="Custom styled"
- *   styles={{
- *     "--checkbox-size": "2rem",
- *     "--checkbox-checked-bg": "#7c3aed",
- *     "--checkbox-radius": "0.5rem",
- *   }}
+ *   label="Large checkbox"
+ *   styles={{ '--checkbox-gap': '1rem' }}
  * />
+ * ```
  *
  * @param {CheckboxProps} props - Component props
- * @returns {React.ReactElement} Checkbox component
+ * @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/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}
+ * @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}
  */
 declare const Checkbox: React$1.ForwardRefExoticComponent<CheckboxProps & React$1.RefAttributes<HTMLInputElement>>;
 
@@ -2901,4 +2751,4 @@ type FPComponent = {
  */
 declare const FP: FPComponent;
 
-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 };
+export { Alert, AlertProps, Article, Aside, Badge, BadgeProps, Box, BoxProps, Caption, Checkbox, CheckboxProps, 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, InputProps, Landmarks, Main, ResponsiveFlexProps, Row, RowProps, Section, Stack, StackProps, Table, Tag, TagProps, TagVariant, Tbody, Td, TextToSpeech, Thead, Tr, UI };