@mezzanine-ui/react 0.15.3 → 1.0.0-alpha.0

package/Checkbox/CheckAll.js

@@ -1,37 +1,50 @@
+'use client';
 import { jsxs, jsx } from 'react/jsx-runtime';
-import { forwardRef, Children, useMemo } from 'react';
-import { checkboxClasses } from '@mezzanine-ui/core/checkbox';
+import { forwardRef, useId, useMemo } from 'react';
 import Checkbox from './Checkbox.js';
-import cx from 'clsx';
+import { assignCheckboxGroupValuesToEvent } from './CheckboxGroup.js';
 
 /**
  * The react component for `mezzanine` check all.
- * Only support controlled.
+ * Wraps a CheckboxGroup and provides a "check all" checkbox that controls all checkboxes in the group.
  */
 const CheckAll = forwardRef(function CheckAll(props, ref) {
-    const { children, className, label, ...rest } = props;
-    const checkboxGroup = children && Children.only(children);
-    const { disabled, name, onChange, options, size, value } = (checkboxGroup === null || checkboxGroup === void 0 ? void 0 : checkboxGroup.props) || {};
-    const enabledOptions = useMemo(() => options === null || options === void 0 ? void 0 : options.filter((option) => !option.disabled), [options]);
-    let allChecked = false;
-    let indeterminate = false;
-    if (enabledOptions && value) {
-        allChecked = enabledOptions.length === value.length;
-        indeterminate = enabledOptions.length > value.length && value.length > 0;
-    }
-    return (jsxs("div", { ...rest, ref: ref, className: cx(checkboxClasses.all, className), children: [jsx("div", { children: jsx(Checkbox, { checked: allChecked, disabled: disabled, indeterminate: indeterminate, inputProps: {
-                        name,
-                    }, onChange: (event) => {
-                        if (onChange) {
-                            if (!event.target.checked) {
-                                onChange([], event);
-                            }
-                            else if (enabledOptions) {
-                                onChange(enabledOptions.map((option) => option.value), event);
-                            }
-                        }
-                    }, size: size, children: label }) }), children] }));
+    const { children, disabled = false, label = 'Check All', } = props;
+    // Generate unique id for the check all checkbox
+    // This is important for accessibility
+    const checkAllId = useId();
+    const checkboxGroupProps = children.props;
+    const { options = [], value = [], onChange } = checkboxGroupProps;
+    // Calculate checked and indeterminate states
+    const { checked, indeterminate } = useMemo(() => {
+        const enabledOptions = options.filter((opt) => !opt.disabled);
+        const enabledValues = enabledOptions.map((opt) => opt.value);
+        const selectedEnabledValues = value.filter((v) => enabledValues.includes(v));
+        if (selectedEnabledValues.length === 0) {
+            return { checked: false, indeterminate: false };
+        }
+        if (selectedEnabledValues.length === enabledValues.length) {
+            return { checked: true, indeterminate: false };
+        }
+        return { checked: false, indeterminate: true };
+    }, [options, value]);
+    const handleCheckAllChange = (event) => {
+        var _a;
+        if (!onChange)
+            return;
+        const isChecked = event.target.checked;
+        const enabledOptions = options.filter((opt) => !opt.disabled);
+        const enabledValues = enabledOptions.map((opt) => opt.value);
+        const disabledOptions = options.filter((opt) => opt.disabled);
+        const disabledValues = disabledOptions.map((opt) => opt.value);
+        const selectedDisabledValues = value.filter((v) => disabledValues.includes(v));
+        const newValue = isChecked
+            ? [...enabledValues, ...selectedDisabledValues]
+            : selectedDisabledValues;
+        const syntheticEvent = assignCheckboxGroupValuesToEvent(event, newValue, (_a = checkboxGroupProps.name) !== null && _a !== void 0 ? _a : '');
+        onChange(syntheticEvent);
+    };
+    return (jsxs("div", { ref: ref, children: [jsx(Checkbox, { checked: checked, disabled: disabled, indeterminate: indeterminate, inputProps: { id: checkAllId }, label: label, name: checkboxGroupProps.name || checkAllId, onChange: handleCheckAllChange }), children] }));
 });
-var CheckAll$1 = CheckAll;
 
-export { CheckAll$1 as default };
+export { CheckAll as default };

package/Checkbox/Checkbox.d.ts

@@ -1,41 +1,119 @@
-import { ChangeEventHandler } from 'react';
-import { CheckboxSize } from '@mezzanine-ui/core/checkbox';
-import { InputCheckProps } from '../_internal/InputCheck';
+import { ChangeEventHandler, Ref } from 'react';
+import { BaseInputProps } from '../Input';
 import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
-export interface CheckboxProps extends Omit<InputCheckProps, 'control' | 'htmlFor'> {
+import { CheckboxPropsBase } from './typings';
+type CheckboxInputElementProps = Omit<NativeElementPropsWithoutKeyAndRef<'input'>, 'checked' | 'defaultChecked' | 'disabled' | 'onChange' | 'placeholder' | 'type' | 'value' | `aria-${'disabled' | 'checked'}`> & {
     /**
-     * Whether the checkbox is checked.
+     * The id attribute can be provided via inputProps, but it's recommended to use the `id` prop directly.
+     * If both are provided, the `id` prop takes precedence.
      */
-    checked?: boolean;
+    id?: string;
     /**
-     * Whether the checkbox is checked by default.
-     * @default false
+     * The name attribute can be provided via inputProps, but it's recommended to use the `name` prop directly.
+     * If both are provided, the `name` prop takes precedence.
      */
-    defaultChecked?: boolean;
+    name?: string;
+};
+export interface CheckboxProps extends Omit<NativeElementPropsWithoutKeyAndRef<'label'>, 'onChange'>, CheckboxPropsBase {
     /**
-     * If true, it means its children checkboxes have at least one unchecked.
-     * @default false
+     * Whether to show an editable input when checkbox is checked.
+     * When `true`, an Input component will be displayed after the checkbox when checked.
+     * If `editableInput` is not provided, default values will be used (name, id, placeholder).
+     *
+     * @example Simple usage
+     * ```tsx
+     * <Checkbox
+     *   label="其他"
+     *   withEditInput
+     *   value={otherValue}
+     *   onChange={(e) => setOtherValue(e.target.value)}
+     * />
+     * ```
+     *
+     * @example With custom editableInput
+     * ```tsx
+     * <Checkbox
+     *   label="其他"
+     *   withEditInput
+     *   editableInput={{
+     *     placeholder: "請輸入其他選項",
+     *     name: "otherOption",
+     *     value: otherValue,
+     *     onChange: (e) => setOtherValue(e.target.value),
+     *   }}
+     * />
+     * ```
+     *
+     * @example With react-hook-form
+     * ```tsx
+     * const { register, watch } = useForm();
+     * const isOtherChecked = watch('options.other');
+     *
+     * <Checkbox
+     *   label="其他"
+     *   {...register('options.other')}
+     *   withEditInput
+     *   editableInput={{
+     *     ...register('otherOption', { required: isOtherChecked }),
+     *     placeholder: "請輸入其他選項",
+     *   }}
+     * />
+     * ```
+     */
+    withEditInput?: boolean;
+    /**
+     * Configuration for editable input that appears when checkbox is checked.
+     * When `withEditInput` is `true` and this prop is not provided, default values will be used.
+     *
+     * Default values when not provided:
+     * - `name`: `{checkboxName}_input` or `{checkboxId}_input`
+     * - `id`: `{checkboxId}_input`
+     * - `placeholder`: "Please enter..."
+     */
+    editableInput?: Omit<BaseInputProps, 'variant'>;
+    /**
+     * The id of input element.
      */
-    indeterminate?: boolean;
+    id?: string;
     /**
      * Since at Mezzanine we use a host element to wrap our input, most derived props will be passed to the host element.
-     *  If you need direct control to the input element, use this prop to provide to it.
+     * If you need direct control to the input element, use this prop to provide to it.
+     */
+    inputProps?: CheckboxInputElementProps;
+    /**
+     * The react ref passed to input element.
      *
-     * Noticed that if you pass in an id within this prop,
-     *  the rendered label element will have `htmlFor` sync with passed in id.
+     * @important When using with react-hook-form's `register`, pass the ref through this prop:
+     * ```tsx
+     * const { register } = useForm();
+     * <Checkbox inputRef={register('fieldName').ref} name="fieldName" />
+     * ```
+     *
+     * For CheckboxGroup, use `Controller` instead of `register` for better array value handling.
      */
-    inputProps?: Omit<NativeElementPropsWithoutKeyAndRef<'input'>, 'checked' | 'defaultChecked' | 'disabled' | 'onChange' | 'placeholder' | 'readOnly' | 'required' | 'type' | 'value' | `aria-${'disabled' | 'checked'}`>;
+    inputRef?: Ref<HTMLInputElement>;
     /**
-     * The change event handler of input in checkbox.
+     * The name attribute of the input element.
+     *
+     * @important When using with react-hook-form or inside a CheckboxGroup, this prop is recommended.
+     * For CheckboxGroup, all checkboxes should share the same `name` attribute.
+     *
+     * When using with react-hook-form's `register`, ensure this matches the field name:
+     * ```tsx
+     * const { register } = useForm();
+     * <Checkbox {...register('fieldName')} inputRef={register('fieldName').ref} />
+     * ```
      */
-    onChange?: ChangeEventHandler<HTMLInputElement>;
+    name?: string;
     /**
-     * The size of checkbox.
-     * @default 'medium'
+     * Invoked by input change event.
      */
-    size?: CheckboxSize;
+    onChange?: ChangeEventHandler<HTMLInputElement>;
     /**
-     * The value of input in checkbox.
+     * The value of checkbox. Used when checkbox is inside a CheckboxGroup.
+     *
+     * @important This prop is required when checkbox is inside a CheckboxGroup.
+     * It is also recommended when integrating with react-hook-form.
      */
     value?: string;
 }

package/Checkbox/Checkbox.js

@@ -1,36 +1,92 @@
-import { jsx } from 'react/jsx-runtime';
-import { forwardRef, useContext } from 'react';
+'use client';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { forwardRef, useContext, useId, useEffect, useMemo, useRef } from 'react';
 import { checkboxClasses } from '@mezzanine-ui/core/checkbox';
+import { CheckedIcon } from '@mezzanine-ui/icons';
 import { useCheckboxControlValue } from '../Form/useCheckboxControlValue.js';
+import Typography from '../Typography/Typography.js';
+import { composeRefs } from '../utils/composeRefs.js';
 import { CheckboxGroupContext } from './CheckboxGroupContext.js';
-import { MezzanineConfig } from '../Provider/context.js';
-import { FormControlContext } from '../Form/FormControlContext.js';
-import InputCheck from '../_internal/InputCheck/InputCheck.js';
+import Icon from '../Icon/Icon.js';
+import Input from '../Input/Input.js';
 import cx from 'clsx';
 
 /**
  * The react component for `mezzanine` checkbox.
  */
 const Checkbox = forwardRef(function Checkbox(props, ref) {
-    const { size: globalSize } = useContext(MezzanineConfig);
-    const { disabled: disabledFromFormControl, severity } = useContext(FormControlContext) || {};
     const checkboxGroup = useContext(CheckboxGroupContext);
-    const { disabled: disabledFromGroup, name: nameFromGroup, size: sizeFromGroup, } = checkboxGroup || {};
-    const { checked: checkedProp, children, defaultChecked, disabled = (disabledFromGroup !== null && disabledFromGroup !== void 0 ? disabledFromGroup : disabledFromFormControl) || false, error = severity === 'error' || false, indeterminate: indeterminateProp = false, onChange: onChangeProp, size = sizeFromGroup || globalSize, value, inputProps, ...rest } = props;
-    const { id: inputId, name = nameFromGroup, ...restInputProps } = inputProps || {};
+    const { disabled: disabledFromGroup, name: nameFromGroup, } = checkboxGroup || {};
+    const { checked: checkedProp, className, defaultChecked, description, disabled = disabledFromGroup, editableInput, id, indeterminate = false, inputProps, inputRef: inputRefProp, label, mode = 'main', name = nameFromGroup, onChange: onChangeProp, value, withEditInput = false, ...rest } = props;
+    const { name: nameFromInputProps, ...restInputProps } = inputProps || {};
+    // Generate unique id if not provided
+    const generatedId = useId();
+    const finalInputId = id !== null && id !== void 0 ? id : generatedId;
+    if (checkboxGroup && value == null) {
+        throw new Error('Checkbox: `value` is required when the checkbox is used inside a CheckboxGroup.');
+    }
     const [checked, onChange] = useCheckboxControlValue({
-        checkboxGroup,
         checked: checkedProp,
         defaultChecked,
         onChange: onChangeProp,
+        checkboxGroup,
         value,
     });
-    const indeterminate = !checked && indeterminateProp;
-    return (jsx(InputCheck, { ...rest, ref: ref, control: jsx("span", { className: cx(checkboxClasses.host, {
-                [checkboxClasses.checked]: checked,
-                [checkboxClasses.indeterminate]: indeterminate,
-            }), children: jsx("input", { ...restInputProps, "aria-checked": indeterminate ? 'mixed' : checked, "aria-disabled": disabled, checked: checked, disabled: disabled, id: inputId, onChange: onChange, name: name, type: "checkbox", value: value }) }), disabled: disabled, error: error, htmlFor: inputId, size: size, children: children }));
+    // Warn when checkbox is standalone and missing a name (helpful for form libs)
+    useEffect(() => {
+        if (!checkboxGroup && !name && !nameFromInputProps && label) {
+            console.warn('Checkbox: The `name` prop is recommended when integrating with react-hook-form. ' +
+                `Checkbox with label "${label}" is missing the \`name\` prop.`);
+        }
+    }, [checkboxGroup, name, nameFromInputProps, label]);
+    const isChecked = checked && !indeterminate;
+    const isIndeterminate = indeterminate;
+    const resolvedName = useMemo(() => {
+        if (name)
+            return name;
+        if (nameFromInputProps)
+            return nameFromInputProps;
+        return finalInputId;
+    }, [finalInputId, name, nameFromInputProps]);
+    const labelColor = useMemo(() => {
+        if (mode === 'chip' && disabled) {
+            return 'text-neutral-light';
+        }
+        return 'text-neutral-solid';
+    }, [mode, disabled]);
+    const inputElementRef = useRef(null);
+    const composedInputRef = useMemo(() => composeRefs([inputRefProp, inputElementRef]), [inputRefProp]);
+    useEffect(() => {
+        if (inputElementRef.current) {
+            inputElementRef.current.indeterminate = isIndeterminate;
+        }
+    }, [isIndeterminate]);
+    const editableInputRef = useRef(null);
+    // Generate default editable input config when withEditInput is true but editableInput is not provided
+    const defaultEditableInput = useMemo(() => {
+        if (!withEditInput)
+            return undefined;
+        if (editableInput) {
+            return editableInput;
+        }
+        // Default values when editableInput is not provided
+        const defaultName = resolvedName ? `${resolvedName}_input` : `${finalInputId}_input`;
+        const defaultId = `${finalInputId}_input`;
+        return {
+            id: defaultId,
+            name: defaultName,
+            placeholder: 'Please enter...',
+        };
+    }, [withEditInput, editableInput, resolvedName, finalInputId]);
+    const shouldShowEditableInput = withEditInput && defaultEditableInput;
+    return (jsxs("div", { className: cx(checkboxClasses.host, className, {
+            [checkboxClasses.checked]: isChecked,
+            [checkboxClasses.indeterminate]: isIndeterminate,
+            [checkboxClasses.disabled]: disabled,
+        }, checkboxClasses.mode(mode)), children: [jsxs("label", { ref: ref, ...rest, className: checkboxClasses.labelContainer, children: [jsx("div", { className: checkboxClasses.inputContainer, children: jsxs("div", { className: checkboxClasses.inputContent, children: [jsx("input", { ...restInputProps, "aria-checked": isIndeterminate ? 'mixed' : checked, "aria-disabled": disabled, checked: isChecked, className: checkboxClasses.input, disabled: disabled, id: finalInputId, name: resolvedName, onChange: onChange, ref: composedInputRef, type: "checkbox", value: value }), mode === 'chip' && isChecked && (jsx(Icon, { "aria-hidden": "true", className: checkboxClasses.icon, color: "brand", icon: CheckedIcon, size: 16 })), mode !== 'chip' && isChecked && (jsx(Icon, { "aria-hidden": "true", className: checkboxClasses.icon, color: "fixed-light", icon: CheckedIcon, size: 7 })), mode !== 'chip' && isIndeterminate && (jsx("span", { "aria-hidden": "true", className: checkboxClasses.indeterminateLine }))] }) }), (label || description) && (jsxs("span", { className: checkboxClasses.textContainer, children: [label && (jsx(Typography, { className: checkboxClasses.label, color: labelColor, variant: "label-primary", children: label })), description && mode !== 'chip' && !shouldShowEditableInput && (jsx(Typography, { className: checkboxClasses.description, color: "text-neutral", variant: "caption", children: description }))] }))] }), shouldShowEditableInput && defaultEditableInput && mode !== 'chip' && !indeterminate && (jsx("div", { className: checkboxClasses.editableInputContainer, children: jsx(Input, { ...defaultEditableInput, ...((!isChecked || disabled) && defaultEditableInput.disabled !== true ? { disabled: true } : {}), inputRef: composeRefs([
+                        defaultEditableInput.inputRef,
+                        editableInputRef,
+                    ]), variant: "base" }) }))] }));
 });
-var Checkbox$1 = Checkbox;
 
-export { Checkbox$1 as default };
+export { Checkbox as default };

package/Checkbox/CheckboxGroup.d.ts

@@ -1,11 +1,56 @@
-import { CheckboxGroupOption, CheckboxSize } from '@mezzanine-ui/core/checkbox';
-import { ChangeEvent, ReactNode } from 'react';
-import { InputCheckGroupProps } from '../_internal/InputCheck';
-export interface CheckboxGroupProps extends Omit<InputCheckGroupProps, 'defaultValue' | 'onChange'> {
+import { CheckboxGroupLayout, CheckboxGroupOption, CheckboxMode } from '@mezzanine-ui/core/checkbox';
+import { ChangeEvent, ChangeEventHandler, ComponentProps, ReactNode } from 'react';
+import { NativeElementPropsWithoutKeyAndRef } from '../utils/jsx-types';
+import Checkbox from './Checkbox';
+export interface CheckboxGroupChangeEventTarget extends HTMLInputElement {
+    values: string[];
+}
+export type CheckboxGroupChangeEvent = ChangeEvent<HTMLInputElement> & {
+    target: CheckboxGroupChangeEventTarget;
+};
+export declare function assignCheckboxGroupValuesToEvent(event: ChangeEvent<HTMLInputElement>, values: string[], name: string): CheckboxGroupChangeEvent;
+type CheckboxGroupOptionInput = CheckboxGroupOption & Omit<ComponentProps<typeof Checkbox>, 'checked' | 'mode' | 'children' | 'defaultChecked' | 'indeterminate' | 'inputProps' | 'inputRef' | 'name' | 'onChange' | 'ref' | 'value'> & {
+    /**
+     * The id of input element.
+     * If not provided, will be auto-generated as `{name}-{value}`.
+     */
+    id?: string;
+    /**
+     * The react ref passed to input element.
+     */
+    inputRef?: ComponentProps<typeof Checkbox>['inputRef'];
+    /**
+     * Additional props for the input element.
+     */
+    inputProps?: ComponentProps<typeof Checkbox>['inputProps'];
+};
+export interface CheckboxGroupLevelConfig {
     /**
-     * The checkboxes in radio group.
+     * Whether the level control is active.
      */
-    children?: ReactNode;
+    active: boolean;
+    /**
+     * Whether the level control checkbox is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The label displayed for the level control checkbox.
+     * @default 'Select all'
+     */
+    label?: string;
+    /**
+     * The mode of level control checkbox.
+     * @default 'main'
+     */
+    mode?: CheckboxMode;
+    /**
+     * Custom onChange handler for the level control.
+     * If not provided, the default behavior (select/deselect all) will be used.
+     */
+    onChange?: ChangeEventHandler<HTMLInputElement>;
+}
+interface CheckboxGroupBaseProps extends NativeElementPropsWithoutKeyAndRef<'div'> {
     /**
      * The default value of checkbox group.
      */
@@ -16,30 +61,67 @@ export interface CheckboxGroupProps extends Omit<InputCheckGroupProps, 'defaultV
      */
     disabled?: boolean;
     /**
-     * The name of checkbox group.
-     * Control the name of checkboxes in group if name not passed to checkbox.
+     * The level control configuration.
+     * When provided, a "select all" checkbox will be rendered above the group.
      */
-    name?: string;
+    level?: CheckboxGroupLevelConfig;
     /**
-     * The onChange of checkbox group.
-     * Will be passed to each checkboxes but composing both instead of overriding.
+     * The layout of checkbox group.
+     * @default 'horizontal'
+     */
+    layout?: CheckboxGroupLayout;
+    /**
+     * The mode of checkboxes in the group.
+     * Control the mode of checkboxes in group if mode not passed to checkbox.
      */
-    onChange?: (value: string[], event: ChangeEvent<HTMLInputElement>) => void;
+    mode?: CheckboxMode;
     /**
-     * The options of checkbox group.
-     * Will be ignored if children passed.
+     * The name of checkbox group.
+     * Control the name of checkboxes in group if name not passed to checkbox.
+     *
+     * @important When integrating with react-hook-form, this prop is highly recommended.
+     * All checkboxes in the group will share the same `name` attribute, which is required
+     * for react-hook-form to correctly collect the selected values as an array.
+     *
+     * @example Using with react-hook-form's Controller:
+     * ```tsx
+     * const { control } = useForm();
+     * <Controller
+     *   name="interests"
+     *   control={control}
+     *   render={({ field }) => (
+     *     <CheckboxGroup
+     *       name="interests"
+     *       value={field.value || []}
+     *       onChange={(e) => field.onChange(e.target.values)}
+     *     >
+     *       <Checkbox value="reading" label="Reading" />
+     *       <Checkbox value="coding" label="Coding" />
+     *     </CheckboxGroup>
+     *   )}
+     * />
+     * ```
      */
-    options?: CheckboxGroupOption[];
+    name?: string;
     /**
-     * The size of checkbox group.
-     * Control the size of checkboxes in group if size not passed to checkbox.
+     * The onChange of checkbox group.
+     * Provides the latest `values` array via `event.target.values`.
      */
-    size?: CheckboxSize;
+    onChange?: (event: CheckboxGroupChangeEvent) => void;
     /**
      * The value of checkbox group.
      */
     value?: string[];
 }
+interface CheckboxGroupOptionsInputProps extends CheckboxGroupBaseProps {
+    children?: never;
+    options: CheckboxGroupOptionInput[];
+}
+interface CheckboxGroupChildrenInputProps extends CheckboxGroupBaseProps {
+    children: ReactNode;
+    options?: never;
+}
+export type CheckboxGroupProps = CheckboxGroupOptionsInputProps | CheckboxGroupChildrenInputProps;
 /**
  * The react component for `mezzanine` checkbox group.
  */