feat!: treat * * * * * as empty and add per-dropdown allowEmpty in dropdownsConfig (#89)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: xrutayisire

README.md

@@ -39,8 +39,8 @@ react-js-cron is written in TypeScript with complete definitions
 
 Be sure that you have these dependencies on your project:
 
-- react (>=17.0.0)
-- antd (>=5.8.0)
+- react (>=18.0.0)
+- antd (>=6.0.0)
 
 ```bash
 # NPM
@@ -194,7 +194,9 @@ CronProps {
   leadingZero?: boolean | ['month-days', 'hours', 'minutes']
 
   /**
-   * Define the default period when the default value is empty.
+   * Define the default period when the value is empty.
+   * When set and the cron value is ambiguous (compatible with multiple periods),
+   * this period will be preferred over the auto-detected one.
    *
    * Default: 'day'
    */
@@ -357,6 +359,10 @@ CronProps {
    *
    * // See global configuration
    * // For 'months', 'month-days', 'week-days', 'hours' and 'minutes'
+   * allowEmpty?: 'always' | 'never' | 'for-default-value'
+   *
+   * // See global configuration
+   * // For 'months', 'month-days', 'week-days', 'hours' and 'minutes'
    * periodicityOnDoubleClick?: boolean
    *
    * // See global configuration
@@ -383,6 +389,7 @@ CronProps {
       disabled?: boolean
       readOnly?: boolean
       allowClear?: boolean
+      allowEmpty?: 'always' | 'never' | 'for-default-value'
       periodicityOnDoubleClick?: boolean
       mode?: 'multiple' | 'single'
       filterOption?: ({
@@ -398,6 +405,7 @@ CronProps {
       disabled?: boolean
       readOnly?: boolean
       allowClear?: boolean
+      allowEmpty?: 'always' | 'never' | 'for-default-value'
       periodicityOnDoubleClick?: boolean
       mode?: 'multiple' | 'single'
       filterOption?: ({
@@ -414,6 +422,7 @@ CronProps {
       disabled?: boolean
       readOnly?: boolean
       allowClear?: boolean
+      allowEmpty?: 'always' | 'never' | 'for-default-value'
       periodicityOnDoubleClick?: boolean
       mode?: 'multiple' | 'single'
       filterOption?: ({
@@ -429,6 +438,7 @@ CronProps {
       disabled?: boolean
       readOnly?: boolean
       allowClear?: boolean
+      allowEmpty?: 'always' | 'never' | 'for-default-value'
       periodicityOnDoubleClick?: boolean
       mode?: 'multiple' | 'single'
       filterOption?: ({
@@ -444,6 +454,7 @@ CronProps {
       disabled?: boolean
       readOnly?: boolean
       allowClear?: boolean
+      allowEmpty?: 'always' | 'never' | 'for-default-value'
       periodicityOnDoubleClick?: boolean
       mode?: 'multiple' | 'single'
       filterOption?: ({
@@ -495,6 +506,7 @@ CronProps {
     prefixMinutesForHourPeriod?: string
     suffixMinutesForHourPeriod?: string
     errorInvalidCron?: string
+    clearButtonText?: string
     weekDays?: string[]
     months?: string[]
     altWeekDays?: string[]

src/Cron.tsx

@@ -1,7 +1,11 @@
 import { Button } from 'antd'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
-import { getCronStringFromValues, setValuesFromCronString } from './converter'
+import {
+  getCronStringFromValues,
+  hasDropdownAllowEmptyError,
+  setValuesFromCronString,
+} from './converter'
 import Hours from './fields/Hours'
 import Minutes from './fields/Minutes'
 import MonthDays from './fields/MonthDays'
@@ -64,6 +68,8 @@ export default function Cron(props: CronProps) {
     getPopupContainer,
   } = props
   const internalValueRef = useRef<string>(value)
+  const initialValueRef = useRef<string>(value)
+  const firstRenderRef = useRef(true)
   const effectiveDefaultPeriod = defaultPeriod ?? 'day'
   const defaultPeriodRef = useRef<PeriodType>(effectiveDefaultPeriod)
   const [period, setPeriod] = useState<PeriodType | undefined>()
@@ -76,6 +82,7 @@ export default function Cron(props: CronProps) {
   const [valueCleared, setValueCleared] = useState<boolean>(false)
   const previousValueCleared = usePrevious(valueCleared)
   const localeJSON = JSON.stringify(locale)
+  const shortcutsJSON = JSON.stringify(shortcuts)
   const dropdownsConfigJSON = JSON.stringify(dropdownsConfig)
 
   useEffect(
@@ -97,6 +104,7 @@ export default function Cron(props: CronProps) {
         setPeriod,
         defaultPeriod,
         allowedPeriods,
+        dropdownsConfig,
       )
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -123,11 +131,12 @@ export default function Cron(props: CronProps) {
           setPeriod,
           defaultPeriod,
           allowedPeriods,
+          dropdownsConfig,
         )
       }
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [value, internalValueRef, localeJSON, allowEmpty, shortcuts],
+    [value, internalValueRef, localeJSON, allowEmpty, shortcutsJSON],
   )
 
   useEffect(
@@ -154,10 +163,42 @@ export default function Cron(props: CronProps) {
         setValue(cron, { selectedPeriod })
         internalValueRef.current = cron
 
-        if (onError) {
-          onError(undefined)
+        if (firstRenderRef.current) {
+          initialValueRef.current = cron
+          firstRenderRef.current = false
+        }
+
+        const isEmptyCron = cron === '* * * * *'
+        const isInitialValue = cron === initialValueRef.current
+        const hasGlobalEmptyError =
+          isEmptyCron &&
+          (allowEmpty === 'never' ||
+            (allowEmpty === 'for-default-value' && !isInitialValue))
+
+        const hasPerDropdownError =
+          !hasGlobalEmptyError &&
+          hasDropdownAllowEmptyError(
+            [
+              minutes ?? [],
+              hours ?? [],
+              monthDays ?? [],
+              months ?? [],
+              weekDays ?? [],
+            ],
+            selectedPeriod,
+            isInitialValue,
+            dropdownsConfig,
+          )
+
+        if (hasGlobalEmptyError || hasPerDropdownError) {
+          setInternalError(true)
+          setError(onError, locale)
+        } else {
+          if (onError) {
+            onError(undefined)
+          }
+          setInternalError(false)
         }
-        setInternalError(false)
       } else if (valueCleared) {
         setValueCleared(false)
       }
@@ -172,6 +213,7 @@ export default function Cron(props: CronProps) {
       minutes,
       humanizeValue,
       valueCleared,
+      allowEmpty,
       dropdownsConfigJSON,
     ],
   )
@@ -215,7 +257,23 @@ export default function Cron(props: CronProps) {
 
       setValueCleared(true)
 
-      if (allowEmpty === 'never' && clearButtonAction === 'empty') {
+      const isEmptyCron = newValue === '* * * * *'
+      const isInitialValue = newValue === initialValueRef.current
+      const hasEmptyError =
+        (allowEmpty === 'never' &&
+          (clearButtonAction === 'empty' || isEmptyCron)) ||
+        (allowEmpty === 'for-default-value' && isEmptyCron && !isInitialValue)
+      const hasPerDropdownError =
+        !hasEmptyError &&
+        isEmptyCron &&
+        hasDropdownAllowEmptyError(
+          [[], [], [], [], []],
+          newPeriod,
+          isInitialValue,
+          dropdownsConfig,
+        )
+
+      if (hasEmptyError || hasPerDropdownError) {
         setInternalError(true)
         setError(onError, locale)
       } else {
@@ -226,7 +284,15 @@ export default function Cron(props: CronProps) {
       }
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [period, setValue, onError, clearButtonAction],
+    [
+      period,
+      setValue,
+      onError,
+      clearButtonAction,
+      allowEmpty,
+      localeJSON,
+      dropdownsConfigJSON,
+    ],
   )
 
   const internalClassName = useMemo(

src/converter.ts

@@ -38,6 +38,7 @@ export function setValuesFromCronString(
   setPeriod: SetValuePeriod,
   defaultPeriod?: PeriodType,
   allowedPeriods?: PeriodType[],
+  dropdownsConfig?: DropdownsConfig,
 ) {
   if (onError) {
     onError(undefined)
@@ -94,6 +95,27 @@ export function setValuesFromCronString(
       setMonthDays(cronParts[2])
       setMonths(cronParts[3])
       setWeekDays(cronParts[4])
+
+      // Check if all parts are empty (= * * * * *)
+      const allEmpty = cronParts.every((part) => part.length === 0)
+      if (allEmpty) {
+        if (
+          allowEmpty === 'never' ||
+          (!firstRender && allowEmpty === 'for-default-value')
+        ) {
+          error = true
+        }
+      }
+
+      // Per-dropdown allowEmpty check
+      if (!error) {
+        error = hasDropdownAllowEmptyError(
+          cronParts,
+          period,
+          firstRender,
+          dropdownsConfig,
+        )
+      }
     } catch {
       // Specific errors are not handle (yet)
       error = true
@@ -106,6 +128,56 @@ export function setValuesFromCronString(
   }
 }
 
+/**
+ * Check if any active dropdown has an empty value that should trigger an error
+ * based on its per-dropdown allowEmpty configuration
+ */
+export function hasDropdownAllowEmptyError(
+  cronParts: number[][],
+  period: PeriodType,
+  allowForDefaultValue: boolean,
+  dropdownsConfig?: DropdownsConfig,
+): boolean {
+  if (!dropdownsConfig || period === 'reboot') return false
+
+  const fields: {
+    key: 'minutes' | 'hours' | 'month-days' | 'months' | 'week-days'
+    index: number
+    isActive: boolean
+  }[] = [
+    { key: 'minutes', index: 0, isActive: period !== 'minute' },
+    {
+      key: 'hours',
+      index: 1,
+      isActive: period !== 'minute' && period !== 'hour',
+    },
+    {
+      key: 'month-days',
+      index: 2,
+      isActive: period === 'year' || period === 'month',
+    },
+    { key: 'months', index: 3, isActive: period === 'year' },
+    {
+      key: 'week-days',
+      index: 4,
+      isActive: period === 'year' || period === 'month' || period === 'week',
+    },
+  ]
+
+  return fields.some(({ key, index, isActive }) => {
+    if (!isActive) return false
+
+    const fieldAllowEmpty = dropdownsConfig[key]?.allowEmpty
+    if (!fieldAllowEmpty) return false
+    if (cronParts[index].length !== 0) return false
+
+    return (
+      fieldAllowEmpty === 'never' ||
+      (fieldAllowEmpty === 'for-default-value' && !allowForDefaultValue)
+    )
+  })
+}
+
 /**
  * Get cron string from values
  */

src/tests/Cron.defaultValue.test.tsx

@@ -801,6 +801,73 @@ describe('Cron defaultValue test suite', () => {
       hoursSelect: undefined,
       minutesSelect: '10',
     },
+    {
+      title:
+        'that * * * * * is not allowed for default value with allowEmpty never',
+      defaultValue: '* * * * *',
+      allowEmpty: 'never',
+      periodSelect: 'minute',
+      monthsSelect: undefined,
+      monthDaysSelect: undefined,
+      weekDaysSelect: undefined,
+      hoursSelect: undefined,
+      minutesSelect: undefined,
+      error: defaultError,
+    },
+    {
+      title: 'that * * * * * is allowed with allowEmpty always',
+      defaultValue: '* * * * *',
+      allowEmpty: 'always',
+      periodSelect: 'minute',
+      monthsSelect: undefined,
+      monthDaysSelect: undefined,
+      weekDaysSelect: undefined,
+      hoursSelect: undefined,
+      minutesSelect: undefined,
+    },
+    {
+      title:
+        'that per-dropdown allowEmpty never triggers error when field is empty',
+      defaultValue: '* * * * 1',
+      dropdownsConfig: {
+        hours: { allowEmpty: 'never' },
+      },
+      periodSelect: 'week',
+      monthsSelect: undefined,
+      monthDaysSelect: undefined,
+      weekDaysSelect: 'MON',
+      hoursSelect: 'every hour',
+      minutesSelect: 'every minute',
+      error: defaultError,
+    },
+    {
+      title:
+        'that per-dropdown allowEmpty for-default-value allows empty for default',
+      defaultValue: '* * * * 1',
+      dropdownsConfig: {
+        hours: { allowEmpty: 'for-default-value' },
+      },
+      periodSelect: 'week',
+      monthsSelect: undefined,
+      monthDaysSelect: undefined,
+      weekDaysSelect: 'MON',
+      hoursSelect: 'every hour',
+      minutesSelect: 'every minute',
+    },
+    {
+      title:
+        'that per-dropdown allowEmpty never does not trigger error when field has value',
+      defaultValue: '0 12 * * 1',
+      dropdownsConfig: {
+        hours: { allowEmpty: 'never' },
+      },
+      periodSelect: 'week',
+      monthsSelect: undefined,
+      monthDaysSelect: undefined,
+      weekDaysSelect: 'MON',
+      hoursSelect: '12',
+      minutesSelect: '0',
+    },
   ]
 
   test.each(cases)(