@usefragments/ui 1.0.0

package/src/components/Checkbox/Checkbox.module.scss

@@ -0,0 +1,256 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Wrapper for checkbox + label
+.wrapper {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  cursor: pointer;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  &[data-has-description] {
+    align-items: flex-start;
+  }
+
+  &[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}
+
+// The checkbox box itself
+.checkbox {
+  @include interactive-base;
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: var(--fui-icon-sm, $fui-icon-sm);
+  height: var(--fui-icon-sm, $fui-icon-sm);
+  margin-top: 0;
+  background-color: var(--fui-field-bg, $fui-bg-elevated);
+  border: 1px solid var(--fui-field-border, $fui-border-strong);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  cursor: inherit;
+
+  &:hover:not([data-disabled]) {
+    border-color: var(--fui-field-border-hover, $fui-text-tertiary);
+  }
+
+  &[data-checked],
+  &[data-indeterminate] {
+    background-color: var(--fui-button-primary-base, $fui-color-accent);
+    border-color: var(
+      --fui-button-primary-border,
+      var(--fui-button-primary-base, #{$fui-color-accent})
+    );
+    box-shadow: inset 0 1px 0 color-mix(in srgb, white 24%, transparent);
+  }
+
+  &[data-checked]:hover:not([data-disabled]),
+  &[data-indeterminate]:hover:not([data-disabled]) {
+    background-color: var(--fui-button-primary-hover, $fui-color-accent);
+    border-color: var(
+      --fui-button-primary-border-hover,
+      var(--fui-button-primary-hover, #{$fui-color-accent})
+    );
+  }
+
+  &[data-invalid] {
+    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+  }
+
+  &[data-invalid][data-checked],
+  &[data-invalid][data-indeterminate] {
+    background-color: var(--fui-color-danger-bg, $fui-color-danger-bg);
+    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+    box-shadow: inset 0 0 0 1px
+      color-mix(in srgb, var(--fui-color-danger-text, #{$fui-color-danger-text}) 35%, transparent);
+  }
+
+  &::before {
+    content: "";
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    width: var(--fui-target-size-min, $fui-target-size-min);
+    height: var(--fui-target-size-min, $fui-target-size-min);
+    transform: translate(-50%, -50%);
+  }
+}
+
+// Size variants
+.sm {
+  width: var(--fui-icon-xs, $fui-icon-xs);
+  height: var(--fui-icon-xs, $fui-icon-xs);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+}
+
+.md {
+  // Default size
+}
+
+.lg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+// Indicator (checkmark or dash)
+.indicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--fui-button-primary-color, #fff);
+
+  svg {
+    width: 0.75rem;
+    height: 0.75rem;
+  }
+
+  // Animation
+  opacity: 0;
+  transform: scale(0.8);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  [data-checked] > &,
+  [data-indeterminate] > & {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  [data-invalid][data-checked] > &,
+  [data-invalid][data-indeterminate] > & {
+    color: var(--fui-color-danger-text, $fui-color-danger-text);
+  }
+}
+
+// Size variant indicators
+.sm .indicator svg {
+  width: 0.625rem;
+  height: 0.625rem;
+}
+
+.lg .indicator svg {
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+// Label content
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-0-5, $fui-space-0-5);
+}
+
+.label {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  user-select: none;
+}
+
+.labelSm {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.labelLg {
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.helper {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// ============================================
+// Card variant: full-width clickable surface that mirrors the RadioGroup
+// card variant. Selection state is driven by `:has([data-checked])` so the
+// styling reacts to the same control state the rest of the component uses.
+// ============================================
+.wrapperCard {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-3, $fui-space-3);
+  width: 100%;
+  height: var(
+    --fui-input-height,
+    $fui-input-height
+  ); // matches Input size="md" so checkbox cards align with form fields
+  box-sizing: border-box;
+  padding: 0 var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  border: 1px solid var(--fui-border-default, $fui-border-default);
+  background: transparent;
+  transition:
+    background var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    box-shadow var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover:not([data-disabled]) {
+    background: var(--fui-bg-hover, $fui-bg-hover);
+    border-color: var(--fui-border-strong, $fui-border-strong);
+  }
+
+  &:focus-within:not([data-disabled]) {
+    @include focus-ring;
+    border-color: var(--fui-button-primary-base, $fui-color-accent);
+  }
+
+  &:has([data-checked]),
+  &:has([data-indeterminate]) {
+    background: color-mix(
+      in srgb,
+      var(--fui-button-primary-base, #{$fui-color-accent}) 13%,
+      transparent
+    );
+    border-color: color-mix(
+      in srgb,
+      var(--fui-button-primary-base, #{$fui-color-accent}) 62%,
+      transparent
+    );
+    box-shadow: 0 0 0 1px
+      color-mix(in srgb, var(--fui-button-primary-base, #{$fui-color-accent}) 28%, transparent);
+  }
+
+  .label {
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .checkbox {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &[data-checked],
+    &[data-indeterminate] {
+      border-color: var(--fui-button-primary-base, $fui-color-accent);
+    }
+
+    &[data-invalid] {
+      border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+    }
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .indicator {
+    transition: none;
+  }
+}

package/src/components/Checkbox/Checkbox.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Checkbox } from '.';
+
+/**
+ * Binary toggle for form fields that require explicit submission.
+ * Supports controlled and uncontrolled use, an indeterminate state, and
+ * sizes sm/md/lg. Prefer Switch for immediate-effect settings.
+ */
+const meta = {
+  title: 'Forms/Checkbox',
+  component: Checkbox,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Binary toggle for form fields requiring explicit submission.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Checkbox size',
+    },
+    variant: {
+      control: 'select',
+      options: ['default', 'card'],
+      description: 'Inline checkbox or full-width clickable card',
+    },
+    indeterminate: { control: 'boolean', description: 'Partial selection state' },
+    disabled: { control: 'boolean' },
+    required: { control: 'boolean' },
+  },
+  args: { size: 'md', variant: 'default', label: 'Accept terms and conditions' },
+} satisfies Meta<typeof Checkbox>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: 'Accept terms and conditions' },
+};
+
+export const Checked: Story = {
+  args: { defaultChecked: true, label: 'Subscribe to newsletter' },
+};
+
+export const WithHelperText: Story = {
+  args: {
+    label: 'Email notifications',
+    helperText: 'Receive email updates about your account activity',
+  },
+};
+
+export const Indeterminate: Story = {
+  args: { indeterminate: true, label: 'Select all' },
+};
+
+export const Large: Story = {
+  args: { size: 'lg', label: 'Large checkbox' },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true, defaultChecked: true, label: 'Disabled checked' },
+};

package/src/components/Checkbox/index.tsx

@@ -0,0 +1,264 @@
+"use client";
+
+import * as React from "react";
+import { Checkbox as BaseCheckbox } from "@base-ui/react/checkbox";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import { mergeAriaIds } from "../../utils/aria";
+import styles from "./Checkbox.module.scss";
+
+// ============================================
+// Types
+// ============================================
+
+/**
+ * Checkbox for boolean or indeterminate selections in forms.
+ * @see https://usefragments.com/components/checkbox
+ */
+export interface CheckboxProps extends Omit<
+  React.HTMLAttributes<HTMLLabelElement>,
+  "onChange" | "defaultChecked"
+> {
+  /** Whether the checkbox is checked */
+  checked?: boolean;
+  /** Default checked state (uncontrolled) */
+  defaultChecked?: boolean;
+  /** Callback when checked state changes */
+  onCheckedChange?: (checked: boolean) => void;
+  /** Alias for onCheckedChange */
+  onChange?: (checked: boolean) => void;
+  /** Whether the checkbox is in an indeterminate state */
+  indeterminate?: boolean;
+  /** Whether the checkbox is disabled */
+  disabled?: boolean;
+  /** Whether the checkbox cannot be changed by the user */
+  readOnly?: boolean;
+  /** Whether the checkbox is required */
+  required?: boolean;
+  /** Size variant.
+   * @default "md" */
+  size?: "sm" | "md" | "lg";
+  /**
+   * Visual variant.
+   * - `default`: inline checkbox next to a label (form-control style).
+   * - `card`: full-width clickable card with the checkbox tucked inside.
+   *   Useful for multi-select question lists, settings toggles, etc.
+   * @default "default"
+   */
+  variant?: "default" | "card";
+  /** Label text */
+  label?: string;
+  /** Helper text shown below the label */
+  helperText?: string;
+  /** @deprecated Use helperText instead. Description text below the label. */
+  description?: string;
+  /** Name attribute for form submission */
+  name?: string;
+  /** ID of the form that owns the hidden input */
+  form?: string;
+  /** Value attribute for form submission */
+  value?: string;
+  /** Value submitted when unchecked */
+  uncheckedValue?: string;
+  /** Ref to the hidden input element */
+  inputRef?: React.Ref<HTMLInputElement>;
+  /** Whether this checkbox controls child checkboxes in a checkbox group */
+  parent?: boolean;
+  /** ID for the checkbox input */
+  id?: string;
+  /** Class applied directly to the checkbox control element */
+  controlClassName?: string;
+  /** Class applied to the label/description content wrapper */
+  contentClassName?: string;
+  /** Accessible label for icon-only mode */
+  "aria-label"?: string;
+  /** Accessible labelled-by relationship for icon-only mode */
+  "aria-labelledby"?: string;
+  /** Accessible described-by relationship */
+  "aria-describedby"?: string;
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function CheckIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+function MinusIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <line x1="5" y1="12" x2="19" y2="12" />
+    </svg>
+  );
+}
+
+// ============================================
+// Component
+// ============================================
+
+const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(function Checkbox(
+  {
+    checked,
+    defaultChecked,
+    onCheckedChange,
+    onChange,
+    indeterminate = false,
+    disabled = false,
+    readOnly = false,
+    required = false,
+    size: sizeProp,
+    variant = "default",
+    label,
+    helperText,
+    description,
+    name,
+    form,
+    value,
+    uncheckedValue,
+    inputRef,
+    parent,
+    className,
+    controlClassName,
+    contentClassName,
+    id,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+    ...htmlProps
+  },
+  ref
+) {
+  const size = useResolvedControlSize(sizeProp);
+  const resolvedHelperText = helperText ?? description;
+  const generatedId = React.useId();
+  const checkboxId = id ?? `checkbox-${generatedId}`;
+  const labelId = label ? `${checkboxId}-label` : undefined;
+  const descriptionId = resolvedHelperText ? `${checkboxId}-description` : undefined;
+
+  const checkboxClasses = [
+    styles.checkbox,
+    size === "sm" && styles.sm,
+    size === "lg" && styles.lg,
+    controlClassName,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const labelClasses = [
+    styles.label,
+    size === "sm" && styles.labelSm,
+    size === "lg" && styles.labelLg,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const wrapperClasses = [styles.wrapper, variant === "card" && styles.wrapperCard, className]
+    .filter(Boolean)
+    .join(" ");
+  const handleCheckedChange = onChange ?? onCheckedChange;
+
+  // If no label/description, render just the checkbox
+  if (!label && !resolvedHelperText) {
+    const iconOnlyHtmlProps = htmlProps as unknown as Record<string, unknown>;
+    return (
+      <BaseCheckbox.Root
+        {...iconOnlyHtmlProps}
+        ref={ref}
+        checked={checked}
+        defaultChecked={defaultChecked}
+        onCheckedChange={handleCheckedChange}
+        indeterminate={indeterminate}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        name={name}
+        form={form}
+        value={value}
+        uncheckedValue={uncheckedValue}
+        inputRef={inputRef}
+        parent={parent}
+        id={checkboxId}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        className={[checkboxClasses, className].filter(Boolean).join(" ")}
+      >
+        <BaseCheckbox.Indicator className={styles.indicator} keepMounted>
+          {indeterminate ? <MinusIcon /> : <CheckIcon />}
+        </BaseCheckbox.Indicator>
+      </BaseCheckbox.Root>
+    );
+  }
+
+  return (
+    <label
+      {...htmlProps}
+      className={wrapperClasses}
+      data-disabled={disabled || undefined}
+      data-has-description={resolvedHelperText ? true : undefined}
+    >
+      <BaseCheckbox.Root
+        ref={ref}
+        checked={checked}
+        defaultChecked={defaultChecked}
+        onCheckedChange={handleCheckedChange}
+        indeterminate={indeterminate}
+        disabled={disabled}
+        readOnly={readOnly}
+        required={required}
+        name={name}
+        form={form}
+        value={value}
+        uncheckedValue={uncheckedValue}
+        inputRef={inputRef}
+        parent={parent}
+        id={checkboxId}
+        aria-label={ariaLabel}
+        aria-labelledby={mergeAriaIds(ariaLabelledBy, labelId)}
+        aria-describedby={mergeAriaIds(ariaDescribedBy, descriptionId)}
+        className={checkboxClasses}
+      >
+        <BaseCheckbox.Indicator className={styles.indicator} keepMounted>
+          {indeterminate ? <MinusIcon /> : <CheckIcon />}
+        </BaseCheckbox.Indicator>
+      </BaseCheckbox.Root>
+      <div className={[styles.content, contentClassName].filter(Boolean).join(" ")}>
+        <span id={labelId} className={labelClasses}>
+          {label}
+        </span>
+        {resolvedHelperText && (
+          <span id={descriptionId} className={styles.helper}>
+            {resolvedHelperText}
+          </span>
+        )}
+      </div>
+    </label>
+  );
+});
+
+export const Checkbox = Object.assign(CheckboxRoot, {
+  Root: CheckboxRoot,
+});