feat(checkbox): add intermediate state

Add intermediate state to checkbox

CTRIB-4794

CHANGELOG.md

@@ -15,12 +15,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
--  `Heading`: fix the default typography when the `as` prop is set.
--  `ImageBlock`: internal changes on caption styles (simply and make reusable).
+-   `Heading`: fix the default typography when the `as` prop is set.
+-   `ImageBlock`: internal changes on caption styles (simply and make reusable).
 
 ### Added
 
--  `Thumbnail`: add `loadingPlaceholderImageRef` to re-use a loaded image as the loading placeholder.
+-   `Thumbnail`: add `loadingPlaceholderImageRef` to re-use a loaded image as the loading placeholder.
+-   `Checkbox`: add intermediate state via `isChecked="intermediate"`
 
 ## [3.7.5][] - 2024-07-25
 

packages/lumx-react/src/components/checkbox/Checkbox.stories.tsx

@@ -33,6 +33,15 @@ export const LabelAndHelper = {
     },
 };
 
+/**
+ * With intermediate state
+ */
+export const IntermediateState = {
+    args: {
+        isChecked: 'intermediate',
+    },
+};
+
 /**
  * Disabled
  */

packages/lumx-react/src/components/checkbox/Checkbox.test.tsx

@@ -39,6 +39,7 @@ describe(`<${Checkbox.displayName}>`, () => {
 
             expect(input).toBeInTheDocument();
             expect(input).not.toBeChecked();
+            expect(input).toHaveAttribute('aria-checked', 'false');
             expect(input).not.toBeDisabled();
         });
 
@@ -51,9 +52,20 @@ describe(`<${Checkbox.displayName}>`, () => {
             expect(checkbox).toHaveClass('lumx-checkbox--is-checked');
 
             expect(input).toBeChecked();
+            expect(input).toHaveAttribute('aria-checked', 'true');
             expect(input).toBeDisabled();
         });
 
+        it('should render intermediate state', () => {
+            const { checkbox, input } = setup({
+                isChecked: 'intermediate',
+            });
+            expect(checkbox).toHaveClass('lumx-checkbox--is-checked');
+
+            expect(input).toBeChecked();
+            expect(input).toHaveAttribute('aria-checked', 'mixed');
+        });
+
         it('should render helper and label', () => {
             const id = 'checkbox1';
             const { props, helper, label, input } = setup({

packages/lumx-react/src/components/checkbox/Checkbox.tsx

@@ -1,13 +1,19 @@
-import React, { useMemo, forwardRef, ReactNode, SyntheticEvent, InputHTMLAttributes } from 'react';
+import React, { forwardRef, InputHTMLAttributes, ReactNode, SyntheticEvent, useMemo } from 'react';
 
 import classNames from 'classnames';
 import { uid } from 'uid';
 
-import { mdiCheck } from '@lumx/icons';
+import { mdiCheck, mdiMinus } from '@lumx/icons';
 
 import { Icon, InputHelper, InputLabel, Theme } from '@lumx/react';
 import { Comp, GenericProps, HasTheme } from '@lumx/react/utils/type';
 import { getRootClassName, handleBasicClasses } from '@lumx/react/utils/className';
+import { useMergeRefs } from '@lumx/react/utils/mergeRefs';
+
+/**
+ * Intermediate state of checkbox.
+ */
+const INTERMEDIATE_STATE = 'intermediate';
 
 /**
  * Defines the props of the component.
@@ -19,8 +25,8 @@ export interface CheckboxProps extends GenericProps, HasTheme {
     id?: string;
     /** Native input ref. */
     inputRef?: React.Ref<HTMLInputElement>;
-    /** Whether it is checked or not. */
-    isChecked?: boolean;
+    /** Whether it is checked or not or intermediate. */
+    isChecked?: boolean | 'intermediate';
     /** Whether the component is disabled or not. */
     isDisabled?: boolean;
     /** Label text. */
@@ -29,10 +35,10 @@ export interface CheckboxProps extends GenericProps, HasTheme {
     name?: string;
     /** Native input value property. */
     value?: string;
-    /** On change callback. */
-    onChange?(isChecked: boolean, value?: string, name?: string, event?: SyntheticEvent): void;
     /** optional props for input */
     inputProps?: InputHTMLAttributes<HTMLInputElement>;
+    /** On change callback. */
+    onChange?(isChecked: boolean, value?: string, name?: string, event?: SyntheticEvent): void;
 }
 
 /**
@@ -77,6 +83,7 @@ export const Checkbox: Comp<CheckboxProps, HTMLDivElement> = forwardRef((props,
         inputProps = {},
         ...forwardedProps
     } = props;
+    const localInputRef = React.useRef<HTMLInputElement>(null);
     const inputId = useMemo(() => id || `${CLASSNAME.toLowerCase()}-${uid()}`, [id]);
 
     const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
@@ -85,14 +92,22 @@ export const Checkbox: Comp<CheckboxProps, HTMLDivElement> = forwardRef((props,
         }
     };
 
+    const intermediateState = isChecked === INTERMEDIATE_STATE;
+
+    React.useEffect(() => {
+        const input = localInputRef.current;
+        if (input) input.indeterminate = intermediateState;
+    }, [intermediateState]);
+
     return (
         <div
             ref={ref}
             {...forwardedProps}
             className={classNames(
                 className,
                 handleBasicClasses({
-                    isChecked,
+                    // Whether state is intermediate class name will "-checked"
+                    isChecked: intermediateState ? true : isChecked,
                     isDisabled,
                     isUnchecked: !isChecked,
                     prefix: CLASSNAME,
@@ -102,7 +117,7 @@ export const Checkbox: Comp<CheckboxProps, HTMLDivElement> = forwardRef((props,
         >
             <div className={`${CLASSNAME}__input-wrapper`}>
                 <input
-                    ref={inputRef}
+                    ref={useMergeRefs(inputRef, localInputRef)}
                     type="checkbox"
                     id={inputId}
                     className={`${CLASSNAME}__input-native`}
@@ -113,14 +128,15 @@ export const Checkbox: Comp<CheckboxProps, HTMLDivElement> = forwardRef((props,
                     checked={isChecked}
                     onChange={handleChange}
                     aria-describedby={helper ? `${inputId}-helper` : undefined}
+                    aria-checked={intermediateState ? 'mixed' : Boolean(isChecked)}
                     {...inputProps}
                 />
 
                 <div className={`${CLASSNAME}__input-placeholder`}>
                     <div className={`${CLASSNAME}__input-background`} />
 
                     <div className={`${CLASSNAME}__input-indicator`}>
-                        <Icon icon={mdiCheck} />
+                        <Icon icon={intermediateState ? mdiMinus : mdiCheck} />
                     </div>
                 </div>
             </div>

packages/site-demo/content/product/components/checkbox/react/default.tsx

@@ -1,31 +1,31 @@
-import { Checkbox } from '@lumx/react';
+import { Checkbox, CheckboxProps } from '@lumx/react';
 import React, { useState } from 'react';
 
 export const App = ({ theme }: any) => {
-    const [value, setValue] = useState(true);
-    const [value2, setValue2] = useState(false);
-    const [value3, setValue3] = useState(false);
+    const useCheckBoxState = (initial: CheckboxProps['isChecked']) => {
+        const [isChecked, onChange] = useState(initial);
+        return { isChecked, onChange };
+    };
 
     return (
         <>
-            <Checkbox isChecked={value} label="Checkbox" theme={theme} onChange={setValue} />
+            <Checkbox label="Checkbox" {...useCheckBoxState(true)} theme={theme} />
 
             <Checkbox
-                isChecked={value2}
-                helper="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed posuere faucibus efficitur."
                 label="Checkbox with help"
+                helper="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+                {...useCheckBoxState(false)}
                 theme={theme}
-                onChange={setValue2}
             />
 
             <Checkbox
-                isChecked={value3}
-                helper="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed posuere faucibus efficitur."
                 label="Disabled checkbox with help"
-                theme={theme}
+                helper="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
                 isDisabled
-                onChange={setValue3}
+                theme={theme}
             />
+
+            <Checkbox label="Checkbox intermediate state" {...useCheckBoxState('intermediate')} theme={theme} />
         </>
     );
 };