@fpkit/acss 3.7.0 → 3.8.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fpkit/acss",
   "description": "A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive Styles.",
   "private": false,
-  "version": "3.7.0",
+  "version": "3.8.0",
   "engines": {
     "node": ">=22.12.0",
     "npm": ">=8.0.0"
@@ -126,5 +126,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "1049811ad793c7a3b0bb37c3d7abdbf171e0a9eb"
+  "gitHead": "28c554debc03c30107f61b62fd70961861b322ea"
 }

package/src/components/checkbox/README.mdx

@@ -0,0 +1,263 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import * as CheckboxStories from "./checkbox.stories";
+
+<Meta of={CheckboxStories} />
+
+# Checkbox
+
+Accessible checkbox component with size and color variants, validation support,
+and comprehensive ARIA attributes.
+
+## Features
+
+- ✅ **WCAG 2.1 AA Compliant** - Meets accessibility standards
+- ✅ **Controlled & Uncontrolled** - Flexible state management
+- ✅ **Indeterminate State** - Three-state checkbox support
+- ✅ **Validation** - Built-in error messaging
+- ✅ **Size Variants** - sm, md, lg
+- ✅ **Color Variants** - primary, secondary, error, success
+- ✅ **Keyboard Navigation** - Full keyboard support
+- ✅ **Custom Styling** - CSS custom properties
+
+## Basic Usage
+
+```tsx
+import { Checkbox } from "@fpkit/acss";
+
+function MyForm() {
+  return <Checkbox id="terms" label="I accept the terms and conditions" />;
+}
+```
+
+## Controlled Mode
+
+Use controlled mode when you need to manage checkbox state in your component:
+
+```tsx
+import { useState } from "react";
+import { Checkbox } from "@fpkit/acss";
+
+function ControlledExample() {
+  const [checked, setChecked] = useState(false);
+
+  return (
+    <Checkbox
+      id="newsletter"
+      label="Subscribe to newsletter"
+      checked={checked}
+      onChange={(e) => setChecked(e.target.checked)}
+    />
+  );
+}
+```
+
+## Uncontrolled Mode
+
+Use uncontrolled mode for simple forms where you read the value on submission:
+
+```tsx
+import { Checkbox } from "@fpkit/acss";
+
+function UncontrolledExample() {
+  const handleSubmit = (e) => {
+    const formData = new FormData(e.target);
+    console.log(formData.get("agree")); // "on" if checked
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Checkbox id="agree" name="agree" label="I agree" defaultChecked={true} />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+## With Validation
+
+Display validation errors and helper text:
+
+```tsx
+<Checkbox
+  id="required"
+  label="Required checkbox"
+  required
+  validationState="invalid"
+  errorMessage="This field is required"
+  description="You must check this box to continue"
+/>
+```
+
+## Indeterminate State
+
+Use for "select all" patterns where some but not all items are selected:
+
+```tsx
+import { useState } from "react";
+import { Checkbox } from "@fpkit/acss";
+
+function SelectAllExample() {
+  const [selectedItems, setSelectedItems] = useState([]);
+  const totalItems = 4;
+
+  const allSelected = selectedItems.length === totalItems;
+  const someSelected = selectedItems.length > 0 && !allSelected;
+
+  return (
+    <Checkbox
+      id="select-all"
+      label="Select all"
+      checked={allSelected}
+      indeterminate={someSelected}
+      onChange={(e) => {
+        if (e.target.checked) {
+          setSelectedItems([1, 2, 3, 4]);
+        } else {
+          setSelectedItems([]);
+        }
+      }}
+    />
+  );
+}
+```
+
+## Size Variants
+
+Choose from three sizes:
+
+```tsx
+<Checkbox id="sm" label="Small" size="sm" />
+<Checkbox id="md" label="Medium (default)" size="md" />
+<Checkbox id="lg" label="Large" size="lg" />
+```
+
+## Color Variants
+
+All colors meet WCAG 2.1 AA contrast requirements:
+
+```tsx
+<Checkbox id="primary" label="Primary (Blue)" color="primary" />
+<Checkbox id="secondary" label="Secondary (Gray)" color="secondary" />
+<Checkbox id="error" label="Error (Red)" color="error" />
+<Checkbox id="success" label="Success (Green)" color="success" />
+```
+
+## Label Positioning
+
+Position labels before or after the checkbox:
+
+```tsx
+<Checkbox id="left" label="Label on left" labelPosition="left" />
+<Checkbox id="right" label="Label on right" labelPosition="right" />
+```
+
+## Custom Styling
+
+Customize appearance using CSS custom properties:
+
+```tsx
+<Checkbox
+  id="custom"
+  label="Custom styled"
+  styles={{
+    "--checkbox-size": "2rem",
+    "--checkbox-checked-bg": "#7c3aed",
+    "--checkbox-radius": "0.5rem",
+  }}
+/>
+```
+
+See [STYLES.mdx](./STYLES.mdx) for complete CSS variable reference.
+
+## Accessibility
+
+### WCAG 2.1 AA Compliance
+
+The Checkbox component implements multiple WCAG success criteria:
+
+- **3.2.2 On Input (Level A)** - Checking the box doesn'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 ratio
+- **2.4.7 Focus Visible (Level AA)** - Clear focus indicators on keyboard
+  navigation
+
+### Keyboard Support
+
+- **Tab** - Move focus to/from checkbox
+- **Space** - Toggle checkbox state
+- **Shift+Tab** - Move focus backward
+
+### Screen Reader Support
+
+- Checkbox state announced (checked/unchecked/indeterminate)
+- Label text announced
+- Description text announced via `aria-describedby`
+- Error messages announced via `aria-errormessage`
+- Required state announced via `aria-required`
+- Disabled state announced via `aria-disabled`
+
+### Best Practices
+
+1. **Always provide labels** - Use `label` or `children` prop for accessible
+   name
+2. **Use semantic colors** - Use `error` variant for validation failures
+3. **Provide descriptions** - Use `description` prop for additional context
+4. **Group related checkboxes** - Use `<fieldset>` and `<legend>` for checkbox
+   groups
+5. **Don't mix modes** - Use either controlled or uncontrolled, not both
+
+## Props
+
+See TypeScript types for complete prop reference with JSDoc documentation.
+
+### Key Props
+
+| Prop              | Type                                               | Default      | Description          |
+| ----------------- | -------------------------------------------------- | ------------ | -------------------- |
+| `id`              | `string`                                           | **required** | Unique identifier    |
+| `label`           | `ReactNode`                                        | -            | Label text           |
+| `children`        | `ReactNode`                                        | -            | Alternative to label |
+| `size`            | `"sm" \| "md" \| "lg"`                             | `"md"`       | Size variant         |
+| `color`           | `"primary" \| "secondary" \| "error" \| "success"` | `"primary"`  | Color variant        |
+| `checked`         | `boolean`                                          | -            | Controlled mode      |
+| `defaultChecked`  | `boolean`                                          | -            | Uncontrolled mode    |
+| `indeterminate`   | `boolean`                                          | `false`      | Indeterminate state  |
+| `disabled`        | `boolean`                                          | -            | Disabled state       |
+| `required`        | `boolean`                                          | `false`      | Required field       |
+| `validationState` | `"valid" \| "invalid" \| "none"`                   | `"none"`     | Validation state     |
+| `errorMessage`    | `string`                                           | -            | Error message        |
+| `description`     | `string`                                           | -            | Helper text          |
+
+## Examples
+
+See Storybook stories for interactive examples:
+
+- **Basic** - Simple checkbox with label
+- **Sizes** - All size variants
+- **Colors** - All color variants
+- **States** - Checked, unchecked, indeterminate, disabled
+- **WithDescription** - Checkbox with helper text
+- **WithError** - Checkbox with validation error
+- **LabelPositions** - Left and right label positioning
+- **Controlled** - Controlled mode example
+- **Uncontrolled** - Uncontrolled mode example
+- **Required** - Required field indicator
+- **ComplexForm** - Complete form example
+- **SelectAll** - Indeterminate "select all" pattern
+- **CustomStyling** - CSS custom property examples
+
+## Related Components
+
+- **Form** - Form wrapper component
+- **Field** - Form field with label and error handling
+- **Input** - Text input component
+- **Select** - Dropdown select component
+
+## Resources
+
+- [ARIA Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [CSS Variables Reference](./STYLES.mdx)

package/src/components/checkbox/STYLES.mdx

@@ -0,0 +1,434 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.React Forms/Inputs/Checkbox/Styles" />
+
+# Checkbox CSS Variables
+
+Complete reference for customizing the Checkbox component using CSS custom
+properties.
+
+## Overview
+
+The Checkbox component uses CSS custom properties for flexible theming and
+customization. All properties follow the standardized naming convention:
+`--checkbox-{element}-{variant}-{property}`.
+
+## Quick Start
+
+```css
+/* Global customization */
+:root {
+  --checkbox-size: 1.5rem;
+  --checkbox-checked-bg: #7c3aed;
+  --checkbox-radius: 0.5rem;
+}
+
+/* Scoped customization */
+.my-form {
+  --checkbox-checked-bg: #10b981;
+  --checkbox-focus-outline-color: #86efac;
+}
+```
+
+```tsx
+/* Inline customization */
+<Checkbox
+  id="custom"
+  label="Custom styled"
+  styles={{
+    "--checkbox-size": "2rem",
+    "--checkbox-checked-bg": "#7c3aed",
+  }}
+/>
+```
+
+## Size Tokens
+
+Control checkbox dimensions with size tokens:
+
+```css
+--checkbox-size-sm: 1rem; /* 16px - Small */
+--checkbox-size-md: 1.25rem; /* 20px - Medium (default) */
+--checkbox-size-lg: 1.5rem; /* 24px - Large */
+```
+
+**Usage:**
+
+```css
+[data-checkbox~="sm"] {
+  --checkbox-size: var(--checkbox-size-sm);
+}
+[data-checkbox~="md"] {
+  --checkbox-size: var(--checkbox-size-md);
+}
+[data-checkbox~="lg"] {
+  --checkbox-size: var(--checkbox-size-lg);
+}
+```
+
+## Base Properties
+
+Core checkbox styling properties:
+
+| Variable                  | Default                      | Description                  |
+| ------------------------- | ---------------------------- | ---------------------------- |
+| `--checkbox-size`         | `var(--checkbox-size-md)`    | Width and height of checkbox |
+| `--checkbox-bg`           | `#ffffff`                    | Background color (unchecked) |
+| `--checkbox-border`       | `0.125rem solid #6b7280`     | Border style                 |
+| `--checkbox-border-color` | `#6b7280`                    | Border color                 |
+| `--checkbox-radius`       | `0.25rem`                    | Border radius (4px)          |
+| `--checkbox-cursor`       | `pointer`                    | Cursor style                 |
+| `--checkbox-transition`   | `all 0.2s cubic-bezier(...)` | Transition animation         |
+
+## Checkmark Properties
+
+Styling for the checkmark indicator:
+
+| Variable                         | Default      | Description            |
+| -------------------------------- | ------------ | ---------------------- |
+| `--checkbox-checkmark-color`     | `#ffffff`    | Checkmark color        |
+| `--checkbox-checkmark-opacity`   | `0`          | Opacity when unchecked |
+| `--checkbox-checkmark-transform` | `scale(0.7)` | Scale when unchecked   |
+
+## Label Properties
+
+Label text styling:
+
+| Variable                  | Default   | Description                          |
+| ------------------------- | --------- | ------------------------------------ |
+| `--checkbox-label-gap`    | `0.5rem`  | Gap between checkbox and label (8px) |
+| `--checkbox-label-fs`     | `1rem`    | Label font size (16px)               |
+| `--checkbox-label-color`  | `inherit` | Label text color                     |
+| `--checkbox-label-cursor` | `pointer` | Label cursor style                   |
+| `--checkbox-label-fw`     | `400`     | Label font weight                    |
+
+## Description Properties
+
+Helper text styling:
+
+| Variable                                      | Default     | Description           |
+| --------------------------------------------- | ----------- | --------------------- |
+| `--checkbox-description-fs`                   | `0.875rem`  | Font size (14px)      |
+| `--checkbox-description-color`                | `#6b7280`   | Text color (Gray 500) |
+| `--checkbox-description-margin-block-start`   | `0.25rem`   | Top margin (4px)      |
+| `--checkbox-description-padding-inline-start` | `calc(...)` | Left padding          |
+
+## Error Message Properties
+
+Error text styling:
+
+| Variable                                | Default     | Description          |
+| --------------------------------------- | ----------- | -------------------- |
+| `--checkbox-error-fs`                   | `0.875rem`  | Font size (14px)     |
+| `--checkbox-error-color`                | `#dc2626`   | Text color (Red 600) |
+| `--checkbox-error-margin-block-start`   | `0.25rem`   | Top margin (4px)     |
+| `--checkbox-error-padding-inline-start` | `calc(...)` | Left padding         |
+
+## Required Indicator
+
+Required asterisk styling:
+
+| Variable                    | Default   | Description     |
+| --------------------------- | --------- | --------------- |
+| `--checkbox-required-color` | `#dc2626` | Color (Red 600) |
+| `--checkbox-required-fw`    | `600`     | Font weight     |
+
+## Color Variants
+
+All color variants meet WCAG 2.1 AA contrast requirements (4.5:1 minimum).
+
+### Primary (Blue)
+
+```css
+--checkbox-primary-checked-bg: #2563eb; /* 4.68:1 contrast */
+--checkbox-primary-checked-border: #2563eb;
+--checkbox-primary-hover-border: #3b82f6;
+--checkbox-primary-focus-outline-color: #93c5fd;
+```
+
+### Secondary (Gray)
+
+```css
+--checkbox-secondary-checked-bg: #4b5563; /* 7.56:1 contrast */
+--checkbox-secondary-checked-border: #4b5563;
+--checkbox-secondary-hover-border: #6b7280;
+--checkbox-secondary-focus-outline-color: #9ca3af;
+```
+
+### Error (Red)
+
+```css
+--checkbox-error-checked-bg: #dc2626; /* 5.14:1 contrast */
+--checkbox-error-checked-border: #dc2626;
+--checkbox-error-hover-border: #ef4444;
+--checkbox-error-focus-outline-color: #fca5a5;
+```
+
+### Success (Green)
+
+```css
+--checkbox-success-checked-bg: #16a34a; /* 4.54:1 contrast */
+--checkbox-success-checked-border: #16a34a;
+--checkbox-success-hover-border: #22c55e;
+--checkbox-success-focus-outline-color: #86efac;
+```
+
+## State Properties
+
+### Hover State
+
+```css
+--checkbox-hover-border-color: #9ca3af;
+--checkbox-hover-bg: #f9fafb;
+```
+
+### Focus State
+
+```css
+--checkbox-focus-outline: 0.125rem solid;
+--checkbox-focus-outline-offset: 0.125rem;
+--checkbox-focus-outline-color: var(--checkbox-primary-focus-outline-color);
+```
+
+### Checked State
+
+```css
+--checkbox-checked-bg: var(--checkbox-primary-checked-bg);
+--checkbox-checked-border: var(--checkbox-primary-checked-border);
+--checkbox-checked-checkmark-opacity: 1;
+--checkbox-checked-checkmark-transform: scale(1);
+```
+
+### Indeterminate State
+
+```css
+--checkbox-indeterminate-bg: var(--checkbox-primary-checked-bg);
+--checkbox-indeterminate-border: var(--checkbox-primary-checked-border);
+--checkbox-indeterminate-dash-width: 0.625rem;
+--checkbox-indeterminate-dash-height: 0.125rem;
+--checkbox-indeterminate-dash-opacity: 1;
+```
+
+### Disabled State
+
+```css
+--checkbox-disabled-bg: #f3f4f6;
+--checkbox-disabled-border-color: #d1d5db;
+--checkbox-disabled-opacity: 0.6;
+--checkbox-disabled-cursor: not-allowed;
+```
+
+### Invalid State
+
+```css
+--checkbox-invalid-border-color: #dc2626;
+--checkbox-invalid-focus-outline-color: #fca5a5;
+```
+
+## Customization Examples
+
+### Example 1: Custom Brand Colors
+
+```css
+:root {
+  /* Purple brand theme */
+  --checkbox-checked-bg: #7c3aed;
+  --checkbox-checked-border: #7c3aed;
+  --checkbox-focus-outline-color: #c4b5fd;
+  --checkbox-hover-border-color: #a78bfa;
+}
+```
+
+### Example 2: Larger Touch Targets
+
+```css
+.mobile-form {
+  /* Increase size for mobile devices */
+  --checkbox-size: 1.75rem; /* 28px */
+  --checkbox-label-fs: 1.125rem; /* 18px */
+  --checkbox-label-gap: 0.75rem; /* 12px */
+}
+```
+
+### Example 3: Rounded/Pill Style
+
+```css
+.rounded-checkboxes {
+  --checkbox-radius: 100rem; /* Fully rounded */
+}
+```
+
+### Example 4: Shadow Instead of Border
+
+```css
+.shadow-checkboxes {
+  --checkbox-border: none;
+  --checkbox-bg: #f3f4f6;
+  --checkbox-checked-bg: #10b981;
+  /* Add shadow via inline styles or custom class */
+}
+```
+
+### Example 5: High Contrast Theme
+
+```css
+.high-contrast {
+  --checkbox-border: 0.1875rem solid #000000; /* 3px black border */
+  --checkbox-checked-bg: #000000;
+  --checkbox-focus-outline: 0.1875rem solid #000000;
+  --checkbox-focus-outline-offset: 0.25rem;
+}
+```
+
+### Example 6: Dark Mode
+
+```css
+.dark-theme {
+  --checkbox-bg: #1f2937; /* Gray 800 */
+  --checkbox-border-color: #4b5563; /* Gray 600 */
+  --checkbox-checked-bg: #3b82f6; /* Blue 500 */
+  --checkbox-checked-border: #3b82f6;
+  --checkbox-label-color: #f3f4f6; /* Gray 100 */
+  --checkbox-description-color: #9ca3af; /* Gray 400 */
+  --checkbox-hover-bg: #374151; /* Gray 700 */
+}
+```
+
+### Example 7: Minimal Style
+
+```css
+.minimal-checkboxes {
+  --checkbox-border: 0.0625rem solid #d1d5db; /* 1px thin border */
+  --checkbox-radius: 0.125rem; /* 2px small radius */
+  --checkbox-checked-bg: #000000;
+  --checkbox-transition: none; /* No animation */
+}
+```
+
+## Complete Variable List
+
+Here's every CSS variable available for customization:
+
+```css
+/* Size Tokens */
+--checkbox-size-sm
+--checkbox-size-md
+--checkbox-size-lg
+
+/* Base Properties */
+--checkbox-size
+--checkbox-bg
+--checkbox-border
+--checkbox-border-color
+--checkbox-radius
+--checkbox-cursor
+--checkbox-transition
+
+/* Checkmark */
+--checkbox-checkmark-color
+--checkbox-checkmark-opacity
+--checkbox-checkmark-transform
+
+/* Label */
+--checkbox-label-gap
+--checkbox-label-fs
+--checkbox-label-color
+--checkbox-label-cursor
+--checkbox-label-fw
+
+/* Description */
+--checkbox-description-fs
+--checkbox-description-color
+--checkbox-description-margin-block-start
+--checkbox-description-padding-inline-start
+
+/* Error */
+--checkbox-error-fs
+--checkbox-error-color
+--checkbox-error-margin-block-start
+--checkbox-error-padding-inline-start
+
+/* Required */
+--checkbox-required-color
+--checkbox-required-fw
+
+/* Primary Variant */
+--checkbox-primary-checked-bg
+--checkbox-primary-checked-border
+--checkbox-primary-hover-border
+--checkbox-primary-focus-outline-color
+
+/* Secondary Variant */
+--checkbox-secondary-checked-bg
+--checkbox-secondary-checked-border
+--checkbox-secondary-hover-border
+--checkbox-secondary-focus-outline-color
+
+/* Error Variant */
+--checkbox-error-checked-bg
+--checkbox-error-checked-border
+--checkbox-error-hover-border
+--checkbox-error-focus-outline-color
+
+/* Success Variant */
+--checkbox-success-checked-bg
+--checkbox-success-checked-border
+--checkbox-success-hover-border
+--checkbox-success-focus-outline-color
+
+/* Hover State */
+--checkbox-hover-border-color
+--checkbox-hover-bg
+
+/* Focus State */
+--checkbox-focus-outline
+--checkbox-focus-outline-offset
+--checkbox-focus-outline-color
+
+/* Checked State */
+--checkbox-checked-bg
+--checkbox-checked-border
+--checkbox-checked-checkmark-opacity
+--checkbox-checked-checkmark-transform
+
+/* Indeterminate State */
+--checkbox-indeterminate-bg
+--checkbox-indeterminate-border
+--checkbox-indeterminate-dash-width
+--checkbox-indeterminate-dash-height
+--checkbox-indeterminate-dash-opacity
+
+/* Disabled State */
+--checkbox-disabled-bg
+--checkbox-disabled-border-color
+--checkbox-disabled-opacity
+--checkbox-disabled-cursor
+
+/* Invalid State */
+--checkbox-invalid-border-color
+--checkbox-invalid-focus-outline-color
+```
+
+## Best Practices
+
+### ✅ Do
+
+- Use CSS custom properties for theming
+- Follow the naming convention when creating new variables
+- Test custom colors for WCAG contrast requirements
+- Use rem units for all size-related properties
+- Scope variables appropriately (:root, class, inline)
+
+### ❌ Don't
+
+- Use pixel units (use rem instead)
+- Override library source files directly
+- Create one-off variables that don't follow the naming pattern
+- Remove required variables (checkbox will break)
+- Use `!important` unless absolutely necessary
+
+## Resources
+
+- [CSS Variables Guide](../../docs/css-variables.md)
+- [WCAG Color Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [Checkbox Component README](./README.mdx)