@cleen/ui 0.1.0

package/src/components/checkbox/Checkbox.tsx

@@ -0,0 +1,246 @@
+import { IconCheck } from '@/components/cleenIcon';
+import { InfoLabels } from '@/components/infoLabels';
+import type { InfoLabelsProps } from '@/components/infoLabels/InfoLabels';
+import { cn } from '@cleen/ui-core';
+import {
+  forwardRef,
+  useEffect,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import { checkedVariants, indeterminateVariants } from './variants';
+
+export type CheckboxProps = Omit<ComponentProps<'input'>, 'title'> & {
+  checked?: boolean | null;
+  defaultChecked?: boolean;
+  title?: ReactNode;
+  label?: ReactNode;
+  sublabel?: ReactNode;
+  variant?: keyof typeof checkedVariants;
+  allowIndeterminate?: boolean;
+  fullTriggerArea?: boolean;
+  classNames?: {
+    container?: string;
+    title?: string;
+    checkboxContainer?: string;
+    checkbox?: string;
+    label?: string;
+    sublabel?: string;
+  };
+  styles?: {
+    container?: CSSProperties;
+    title?: CSSProperties;
+    checkboxContainer?: CSSProperties;
+    checkbox?: CSSProperties;
+    label?: CSSProperties;
+    sublabel?: CSSProperties;
+  };
+  infoLabels?: InfoLabelsProps;
+  onChange?: (e: ChangeEvent<HTMLInputElement>) => void;
+};
+
+/**
+ * The `Checkbox` component is a controlled or uncontrolled input that supports checked, unchecked, and optional indeterminate states.
+ *
+ * - Pass `checked` (boolean or `null` for indeterminate) to use as a controlled input, or use `defaultChecked` for uncontrolled mode.
+ * - Set `allowIndeterminate` to cycle through checked → indeterminate → unchecked on each change.
+ * - Supports `label`, `sublabel`, and `title` for rich labelling above and beside the input.
+ * - Use `infoLabels` to show an error, info, or subtitle message below the checkbox.
+ * - Set `fullTriggerArea` to make the entire label row clickable instead of just the checkbox box.
+ * - Accepts `classNames` and `styles` to customize: `container`, `title`, `checkboxContainer`, `checkbox`, `label`, `sublabel`.
+ */
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
+  function Checkbox(
+    {
+      checked,
+      defaultChecked = false,
+      className,
+      classNames,
+      style,
+      styles,
+      onChange,
+      disabled,
+      id,
+      title,
+      label,
+      sublabel,
+      variant = 'primary',
+      allowIndeterminate = false,
+      fullTriggerArea = false,
+      infoLabels,
+      ...props
+    },
+    ref
+  ) {
+    const isControlled = typeof checked === 'boolean' || checked === null;
+    const [internalChecked, setInternalChecked] = useState<boolean | null>(
+      defaultChecked
+    );
+    const inputRef = useRef<HTMLInputElement | null>(null);
+
+    // Keep both internal ref and forwarded ref in sync
+    const setInputRef = (el: HTMLInputElement | null) => {
+      inputRef.current = el;
+      if (!ref) {
+        return;
+      }
+
+      if (typeof ref === 'function') {
+        ref(el);
+      } else {
+        (ref as RefObject<HTMLInputElement | null>).current = el;
+      }
+    };
+
+    useEffect(() => {
+      if (!isControlled) {
+        setInternalChecked(defaultChecked);
+      }
+    }, [defaultChecked, isControlled]);
+
+    useEffect(() => {
+      if (inputRef.current) {
+        inputRef.current.indeterminate = allowIndeterminate && checked === null;
+      }
+    }, [checked, allowIndeterminate]);
+
+    const currentChecked = isControlled ? checked : internalChecked;
+
+    const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
+      let newValue;
+
+      if (allowIndeterminate) {
+        switch (currentChecked) {
+          case true:
+            newValue = null;
+            break;
+
+          case false:
+            newValue = true;
+            break;
+
+          case null:
+          default:
+            newValue = false;
+            break;
+        }
+      } else {
+        newValue = !currentChecked;
+      }
+
+      if (!isControlled) {
+        setInternalChecked(newValue);
+      }
+
+      onChange?.({
+        ...e,
+        target: {
+          ...e.target,
+          checked: newValue as boolean,
+        },
+      });
+    };
+
+    const checkboxContent = (
+      <>
+        <label
+          className={cn(
+            'cleen-bg-white cleen-transition-all cleen-duration-200 hover:cleen-bg-gray/10 hover:cleen-shadow-[0px_0px_0px_4px_rgba(var(--cleen-gray),0.1)] cleen-border cleen-border-gray/30 cleen-rounded cleen-ring-primary cleen-size-5 cleen-cursor-pointer',
+            {
+              [checkedVariants[variant]]: currentChecked,
+              [indeterminateVariants[variant]]: currentChecked === null,
+            },
+            disabled && 'cleen-cursor-not-allowed cleen-pointer-events-none',
+            'cleen-flex cleen-items-center cleen-justify-center',
+            classNames?.checkbox
+          )}
+          style={styles?.checkbox}
+        >
+          <input
+            ref={setInputRef}
+            type="checkbox"
+            disabled={disabled}
+            className="cleen-hidden"
+            checked={currentChecked === true}
+            onChange={handleChange}
+            id={id}
+            {...props}
+          />
+
+          {currentChecked === null ? (
+            <span className="cleen-block cleen-m-auto cleen-border cleen-border-white cleen-rounded-sm cleen-w-2.5 cleen-h-0.5 cleen-size-3" />
+          ) : currentChecked ? (
+            <IconCheck className="cleen-stroke-[3px] cleen-size-3 cleen-text-white" />
+          ) : null}
+        </label>
+
+        {(label || sublabel) && (
+          <div className="cleen-text-gray/80">
+            <label
+              htmlFor={id}
+              className={cn('cleen-flex', classNames?.label)}
+              style={styles?.label}
+            >
+              {label}
+            </label>
+
+            <label
+              htmlFor={id}
+              className={cn(
+                'cleen-font-normal cleen-text-gray/60 cleen-text-sm cleen-leading-5',
+                classNames?.sublabel
+              )}
+              style={styles?.sublabel}
+            >
+              {sublabel}
+            </label>
+          </div>
+        )}
+      </>
+    );
+
+    const checkboxContainerProps = {
+      className: cn(
+        'cleen-flex cleen-items-start cleen-gap-2 cleen-ml-1',
+        {
+          'cleen-opacity-50': disabled,
+        },
+        classNames?.checkboxContainer
+      ),
+      style: styles?.checkboxContainer,
+    };
+
+    return (
+      <div className={cn('cleen', className)} style={style}>
+        <div className={cn(classNames?.container)} style={styles?.container}>
+          {title && (
+            <label
+              className={cn(
+                'cleen-block cleen-mb-1.5 cleen-font-medium cleen-text-gray/90 cleen-text-sm cleen-leading-6',
+                classNames?.title
+              )}
+              style={styles?.title}
+            >
+              {title}
+            </label>
+          )}
+
+          {fullTriggerArea ? (
+            <label {...checkboxContainerProps}>{checkboxContent}</label>
+          ) : (
+            <div {...checkboxContainerProps}>{checkboxContent}</div>
+          )}
+
+          {(infoLabels?.errorMessage ||
+            infoLabels?.infoMessage ||
+            infoLabels?.subtitle) && <InfoLabels {...infoLabels} />}
+        </div>
+      </div>
+    );
+  }
+);

package/src/components/checkbox/index.ts

@@ -0,0 +1 @@
+export { Checkbox, type CheckboxProps } from './Checkbox';

package/src/components/checkbox/variants.ts

@@ -0,0 +1,13 @@
+export const checkedVariants = {
+  primary:
+    'cleen-bg-primary cleen-transition-all cleen-duration-200 hover:cleen-bg-primary hover:cleen-shadow-[0px_0px_0px_4px_rgba(var(--cleen-primary),0.25)]',
+  error:
+    'cleen-bg-error cleen-transition-all cleen-duration-200 hover:cleen-bg-error hover:cleen-shadow-[0px_0px_0px_4px_rgba(var(--cleen-error),0.25)]',
+} as const;
+
+export const indeterminateVariants = {
+  primary:
+    'cleen-bg-primary/60 cleen-transition-all cleen-duration-200 hover:cleen-bg-primary/60 hover:cleen-shadow-[0px_0px_0px_4px_rgba(var(--cleen-primary),0.25)]',
+  error:
+    'cleen-bg-error/60 cleen-transition-all cleen-duration-200 hover:cleen-bg-error/60 hover:cleen-shadow-[0px_0px_0px_4px_rgba(var(--cleen-error),0.25)]',
+} as const;

package/src/components/checkboxGroup/CheckboxGroup.tsx

@@ -0,0 +1,163 @@
+import { InfoLabels } from '@/components/infoLabels';
+import type { InfoLabelsProps } from '@/components/infoLabels/InfoLabels';
+import {
+  useMemo,
+  useState,
+  type ChangeEvent,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+import { cn } from '@cleen/ui-core';
+import { Checkbox, type CheckboxProps } from '@/components/checkbox/Checkbox';
+
+export interface CheckboxGroupProps extends Omit<
+  ComponentProps<'div'>,
+  'onChange'
+> {
+  label?: ReactNode;
+  checkboxes?: CheckboxProps[];
+  onChange?: (checkbox: CheckboxProps, checkboxArray?: CheckboxProps[]) => void;
+  allowIndeterminate?: boolean;
+  infoLabels?: InfoLabelsProps;
+  requiresAtLeastOneOptions?: {
+    title?: ReactNode;
+    subtitle?: ReactNode;
+  };
+  classNames?: {
+    container?: string;
+    label?: string;
+    checkboxes?: string;
+    checkboxContainer?: string;
+    requiresAtLeastOne?: {
+      container?: string;
+      title?: string;
+      subtitle?: string;
+    };
+  };
+  styles?: {
+    container?: CSSProperties;
+    label?: CSSProperties;
+    checkboxes?: CSSProperties;
+    checkboxContainer?: CSSProperties;
+    requiresAtLeastOne?: {
+      container?: CSSProperties;
+      title?: CSSProperties;
+      subtitle?: CSSProperties;
+    };
+  };
+}
+
+/**
+ * The `CheckboxGroup` component renders a labelled list of `Checkbox` items and manages their collective state.
+ *
+ * - Pass an array of `checkboxes` (each with an `id` for accurate tracking) to populate the group.
+ * - The `onChange` callback receives the changed checkbox and the full updated array when all items have an `id`.
+ * - Set `allowIndeterminate` to propagate indeterminate support to each checkbox in the group.
+ * - Use `requiresAtLeastOneOptions` to display a validation error when all checkboxes are unchecked.
+ * - Use `infoLabels` for static error, info, or subtitle messages below the group.
+ * - Accepts `classNames` and `styles` to customize: `container`, `label`, `checkboxes`, `checkboxContainer`, `requiresAtLeastOne`.
+ */
+export const CheckboxGroup = ({
+  label,
+  checkboxes,
+  allowIndeterminate,
+  infoLabels,
+  requiresAtLeastOneOptions,
+  classNames,
+  styles,
+  onChange,
+  ...props
+}: CheckboxGroupProps) => {
+  const [hasChangedOnce, setHasChangedOnce] = useState(false);
+
+  const errorMessage = useMemo(() => {
+    if (
+      requiresAtLeastOneOptions &&
+      hasChangedOnce &&
+      checkboxes?.every(checkbox => checkbox.checked === false)
+    ) {
+      return requiresAtLeastOneOptions.title;
+    }
+
+    return infoLabels?.errorMessage;
+  }, [
+    requiresAtLeastOneOptions,
+    infoLabels?.errorMessage,
+    checkboxes,
+    hasChangedOnce,
+  ]);
+
+  const handleChange = (
+    e: ChangeEvent<HTMLInputElement>,
+    checkbox: CheckboxProps
+  ) => {
+    const newCheckbox = {
+      ...checkbox,
+      checked: e.target.checked,
+    };
+    let newArr: CheckboxProps[] | undefined = undefined;
+
+    if (checkboxes && checkbox?.id) {
+      newArr = [...checkboxes]?.map(cb =>
+        cb.id === checkbox.id ? newCheckbox : cb
+      );
+    }
+
+    onChange?.(newCheckbox, newArr);
+    setHasChangedOnce(true);
+  };
+
+  return (
+    <div className={cn('cleen')} {...props}>
+      <div
+        className={cn(
+          'cleen-flex cleen-flex-col cleen-gap-2',
+          classNames?.container
+        )}
+        style={styles?.container}
+      >
+        {label && (
+          <label
+            className={cn(
+              'cleen-block cleen-mb-1.5 cleen-font-medium cleen-text-gray/90 cleen-text-sm cleen-leading-6',
+              classNames?.label
+            )}
+            style={styles?.label}
+          >
+            {label}
+          </label>
+        )}
+
+        <div
+          className={cn(
+            'cleen-flex cleen-flex-col cleen-gap-3 cleen-pl-2',
+            classNames?.checkboxes
+          )}
+          style={styles?.checkboxes}
+        >
+          {checkboxes?.map(checkbox => (
+            <div
+              key={checkbox.id}
+              className={cn('cleen-flex', classNames?.checkboxContainer)}
+              style={styles?.checkboxContainer}
+            >
+              <Checkbox
+                allowIndeterminate={allowIndeterminate}
+                {...checkbox}
+                fullTriggerArea
+                onChange={e => handleChange(e, checkbox)}
+              />
+            </div>
+          ))}
+        </div>
+
+        {(errorMessage || infoLabels?.infoMessage || infoLabels?.subtitle) && (
+          <InfoLabels {...infoLabels} errorMessage={errorMessage} />
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default CheckboxGroup;

package/src/components/checkboxGroup/index.ts

@@ -0,0 +1 @@
+export { CheckboxGroup, type CheckboxGroupProps } from './CheckboxGroup';