feat(TimeField): support interval steps (#1924)

kricsleo · web-flow · commit 7b8424b1e08b · 2025-05-26T22:36:30.000+08:00
* feat(TimeField): support interval steps

* refactor: use aggregated `step`

* docs: update props

* docs: typo
diff --git a/docs/content/meta/DateFieldRoot.md b/docs/content/meta/DateFieldRoot.md
@@ -117,6 +117,12 @@
     'description': '<p>When <code>true</code>, indicates that the user must set the value before the owning form can be submitted.</p>\n',
     'type': 'boolean',
     'required': false
+  },
+  {
+    'name': 'step',
+    'description': '<p>The stepping interval for the time fields. Defaults to <code>1</code>.</p>\n',
+    'type': 'DateStep',
+    'required': false
   }
 ]" />
 
diff --git a/docs/content/meta/DatePickerRoot.md b/docs/content/meta/DatePickerRoot.md
@@ -173,6 +173,12 @@
     'type': 'boolean',
     'required': false
   },
+  {
+    'name': 'step',
+    'description': '<p>The stepping interval for the time fields. Defaults to <code>1</code>.</p>\n',
+    'type': 'DateStep',
+    'required': false
+  },
   {
     'name': 'weekdayFormat',
     'description': '<p>The format to use for the weekday strings provided via the weekdays slot prop</p>\n',
diff --git a/docs/content/meta/DateRangeFieldRoot.md b/docs/content/meta/DateRangeFieldRoot.md
@@ -117,6 +117,12 @@
     'description': '<p>When <code>true</code>, indicates that the user must set the value before the owning form can be submitted.</p>\n',
     'type': 'boolean',
     'required': false
+  },
+  {
+    'name': 'step',
+    'description': '<p>The stepping interval for the time fields. Defaults to <code>1</code>.</p>\n',
+    'type': 'DateStep',
+    'required': false
   }
 ]" />
 
diff --git a/docs/content/meta/DateRangePickerRoot.md b/docs/content/meta/DateRangePickerRoot.md
@@ -193,6 +193,12 @@
     'type': 'boolean',
     'required': false
   },
+  {
+    'name': 'step',
+    'description': '<p>The stepping interval for the time fields. Defaults to <code>1</code>.</p>\n',
+    'type': 'DateStep',
+    'required': false
+  },
   {
     'name': 'weekdayFormat',
     'description': '<p>The format to use for the weekday strings provided via the weekdays slot prop</p>\n',
diff --git a/docs/content/meta/TimeFieldRoot.md b/docs/content/meta/TimeFieldRoot.md
@@ -111,6 +111,12 @@
     'description': '<p>When <code>true</code>, indicates that the user must set the value before the owning form can be submitted.</p>\n',
     'type': 'boolean',
     'required': false
+  },
+  {
+    'name': 'step',
+    'description': '<p>The stepping interval for the time fields. Defaults to <code>1</code>.</p>\n',
+    'type': 'DateStep',
+    'required': false
   }
 ]" />
 
diff --git a/packages/core/src/DateField/DateFieldInput.vue b/packages/core/src/DateField/DateFieldInput.vue
@@ -29,6 +29,7 @@ const {
   lastKeyZero,
   placeholder: rootContext.placeholder,
   hourCycle: rootContext.hourCycle,
+  step: rootContext.step,
   segmentValues: rootContext.segmentValues,
   formatter: rootContext.formatter,
   part: props.part,
diff --git a/packages/core/src/DateField/DateFieldRoot.vue b/packages/core/src/DateField/DateFieldRoot.vue
@@ -4,7 +4,7 @@ import type { DateValue } from '@internationalized/date'
 import type { Ref } from 'vue'
 import type { Matcher } from '@/date'
 import type { PrimitiveProps } from '@/Primitive'
-import type { Formatter } from '@/shared'
+import type { DateStep, Formatter } from '@/shared'
 import type { Granularity, HourCycle, SegmentPart, SegmentValueObj } from '@/shared/date'
 import type { Direction, FormFieldProps } from '@/shared/types'
 import { hasTime, isBefore } from '@/date'
@@ -15,8 +15,8 @@ import {
   getSegmentElements,
   initializeSegmentValues,
   isSegmentNavigationKey,
+  normalizeDateStep,
   syncSegmentValues,
-
 } from '@/shared/date'
 
 type DateFieldRootContext = {
@@ -29,6 +29,7 @@ type DateFieldRootContext = {
   readonly: Ref<boolean>
   formatter: Formatter
   hourCycle: HourCycle
+  step: Ref<DateStep>
   segmentValues: Ref<SegmentValueObj>
   segmentContents: Ref<{ part: SegmentPart, value: string }[]>
   elements: Ref<Set<HTMLElement>>
@@ -47,6 +48,8 @@ export interface DateFieldRootProps extends PrimitiveProps, FormFieldProps {
   modelValue?: DateValue | null
   /** The hour cycle used for formatting times. Defaults to the local preference */
   hourCycle?: HourCycle
+  /** The stepping interval for the time fields. Defaults to `1`. */
+  step?: DateStep
   /** The granularity to use for formatting times. Defaults to day if a CalendarDate is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity */
   granularity?: Granularity
   /** Whether or not to hide the time zone segment of the field */
@@ -139,6 +142,8 @@ const placeholder = useVModel(props, 'placeholder', emits, {
   passive: (props.placeholder === undefined) as false,
 }) as Ref<DateValue>
 
+const step = computed(() => normalizeDateStep(props))
+
 const inferredGranularity = computed(() => {
   if (props.granularity)
     return !hasTime(placeholder.value) ? 'day' : props.granularity
@@ -257,6 +262,7 @@ provideDateFieldRootContext({
   disabled,
   formatter,
   hourCycle: props.hourCycle,
+  step,
   readonly,
   segmentValues,
   isInvalid,
diff --git a/packages/core/src/DateRangeField/DateRangeFieldInput.vue b/packages/core/src/DateRangeField/DateRangeFieldInput.vue
@@ -32,6 +32,7 @@ const {
   lastKeyZero,
   placeholder: rootContext.placeholder,
   hourCycle: rootContext.hourCycle,
+  step: rootContext.step,
   segmentValues: rootContext.segmentValues[props.type],
   formatter: rootContext.formatter,
   part: props.part,
diff --git a/packages/core/src/DateRangeField/DateRangeFieldRoot.vue b/packages/core/src/DateRangeField/DateRangeFieldRoot.vue
@@ -5,7 +5,7 @@ import type { Ref } from 'vue'
 import type { Matcher } from '@/date'
 import type { PrimitiveProps } from '@/Primitive'
 import type { Formatter } from '@/shared'
-import type { DateRange, Granularity, HourCycle, SegmentPart, SegmentValueObj } from '@/shared/date'
+import type { DateRange, DateStep, Granularity, HourCycle, SegmentPart, SegmentValueObj } from '@/shared/date'
 import type { Direction, FormFieldProps } from '@/shared/types'
 import {
   areAllDaysBetweenValid,
@@ -23,6 +23,7 @@ import {
 
   initializeSegmentValues,
   isSegmentNavigationKey,
+  normalizeDateStep,
 
   syncSegmentValues,
 } from '@/shared/date'
@@ -40,6 +41,7 @@ type DateRangeFieldRootContext = {
   readonly: Ref<boolean>
   formatter: Formatter
   hourCycle: HourCycle
+  step: Ref<DateStep>
   segmentValues: Record<DateRangeType, Ref<SegmentValueObj>>
   segmentContents: Ref<{ start: { part: SegmentPart, value: string }[], end: { part: SegmentPart, value: string }[] }>
   elements: Ref<Set<HTMLElement>>
@@ -58,6 +60,8 @@ export interface DateRangeFieldRootProps extends PrimitiveProps, FormFieldProps
   modelValue?: DateRange | null
   /** The hour cycle used for formatting times. Defaults to the local preference */
   hourCycle?: HourCycle
+  /** The stepping interval for the time fields. Defaults to `1`. */
+  step?: DateStep
   /** The granularity to use for formatting times. Defaults to day if a CalendarDate is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity */
   granularity?: Granularity
   /** Whether or not to hide the time zone segment of the field */
@@ -139,6 +143,8 @@ const placeholder = useVModel(props, 'placeholder', emits, {
   passive: (props.placeholder === undefined) as false,
 }) as Ref<DateValue>
 
+const step = computed(() => normalizeDateStep(props))
+
 const inferredGranularity = computed(() => {
   if (props.granularity)
     return !hasTime(placeholder.value) ? 'day' : props.granularity
@@ -342,6 +348,7 @@ provideDateRangeFieldRootContext({
   disabled,
   formatter,
   hourCycle: props.hourCycle,
+  step,
   readonly,
   segmentValues: { start: startSegmentValues, end: endSegmentValues },
   isInvalid,
diff --git a/packages/core/src/TimeField/TimeField.test.ts b/packages/core/src/TimeField/TimeField.test.ts
@@ -179,6 +179,44 @@ describe('timeField', async () => {
     expect(second).toHaveTextContent(cycle('second'))
   })
 
+  it('increase/decrease segments with step', async () => {
+    const step = 2
+    const { user, hour, getByTestId } = setup({
+      timeFieldProps: {
+        modelValue: zonedDateTime,
+        granularity: 'second',
+        step: { minute: step, second: step },
+      },
+    })
+
+    function cycle(segment: keyof TimeFields, sign: number) {
+      return String(zonedDateTime.cycle(segment, sign)[segment])
+    }
+
+    const minute = getByTestId('minute')
+    const second = getByTestId('second')
+
+    await user.click(hour)
+    await user.keyboard(kbd.ARROW_DOWN)
+    expect(hour).toHaveTextContent(cycle('hour', -1))
+    await user.keyboard(kbd.ARROW_UP)
+    expect(hour).toHaveTextContent(cycle('hour', 0))
+
+    await user.click(minute)
+    await user.keyboard(kbd.ARROW_DOWN)
+    expect(minute).toHaveTextContent(cycle('minute', -step))
+    await user.keyboard(kbd.ARROW_UP)
+    await user.keyboard(kbd.ARROW_UP)
+    expect(minute).toHaveTextContent(cycle('minute', step))
+
+    await user.click(second)
+    await user.keyboard(kbd.ARROW_DOWN)
+    expect(second).toHaveTextContent(cycle('second', -step))
+    await user.keyboard(kbd.ARROW_UP)
+    await user.keyboard(kbd.ARROW_UP)
+    expect(second).toHaveTextContent(cycle('second', step))
+  })
+
   it('navigates segments using the arrow keys', async () => {
     const { getByTestId, user, hour } = setup({
       timeFieldProps: {
diff --git a/packages/core/src/TimeField/TimeFieldInput.vue b/packages/core/src/TimeField/TimeFieldInput.vue
@@ -29,6 +29,7 @@ const {
   lastKeyZero,
   placeholder: rootContext.placeholder,
   hourCycle: rootContext.hourCycle,
+  step: rootContext.step,
   segmentValues: rootContext.segmentValues,
   formatter: rootContext.formatter,
   part: props.part,
diff --git a/packages/core/src/TimeField/TimeFieldRoot.vue b/packages/core/src/TimeField/TimeFieldRoot.vue
@@ -1,10 +1,9 @@
 <script lang="ts">
 import type { DateValue } from '@internationalized/date'
-
 import type { Ref } from 'vue'
 import type { PrimitiveProps } from '@/Primitive'
 import type { Formatter } from '@/shared'
-import type { HourCycle, SegmentPart, SegmentValueObj, TimeValue } from '@/shared/date'
+import type { DateStep, HourCycle, SegmentPart, SegmentValueObj, TimeValue } from '@/shared/date'
 import type { Direction, FormFieldProps } from '@/shared/types'
 import { getLocalTimeZone, isEqualDay, Time, toCalendarDateTime, today } from '@internationalized/date'
 import { isBefore } from '@/date'
@@ -16,6 +15,7 @@ import {
 
   initializeTimeSegmentValues,
   isSegmentNavigationKey,
+  normalizeDateStep,
 
   syncTimeSegmentValues,
 
@@ -30,6 +30,7 @@ type TimeFieldRootContext = {
   readonly: Ref<boolean>
   formatter: Formatter
   hourCycle: HourCycle
+  step: Ref<DateStep>
   segmentValues: Ref<SegmentValueObj>
   segmentContents: Ref<{ part: SegmentPart, value: string }[]>
   elements: Ref<Set<HTMLElement>>
@@ -48,6 +49,8 @@ export interface TimeFieldRootProps extends PrimitiveProps, FormFieldProps {
   modelValue?: TimeValue | null
   /** The hour cycle used for formatting times. Defaults to the local preference */
   hourCycle?: HourCycle
+  /** The stepping interval for the time fields. Defaults to `1`. */
+  step?: DateStep
   /** The granularity to use for formatting times. Defaults to minute if a Time is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity */
   granularity?: 'hour' | 'minute' | 'second'
   /** Whether or not to hide the time zone segment of the field */
@@ -125,6 +128,8 @@ const { primitiveElement, currentElement: parentElement }
   = usePrimitiveElement()
 const segmentElements = ref<Set<HTMLElement>>(new Set())
 
+const step = computed(() => normalizeDateStep(props))
+
 const convertedMinValue = computed(() => minValue.value ? convertValue(minValue.value) : undefined)
 const convertedMaxValue = computed(() => maxValue.value ? convertValue(maxValue.value) : undefined)
 
@@ -289,6 +294,7 @@ provideTimeFieldRootContext({
   disabled,
   formatter,
   hourCycle: props.hourCycle,
+  step,
   readonly,
   segmentValues,
   isInvalid,
diff --git a/packages/core/src/shared/date/index.ts b/packages/core/src/shared/date/index.ts
@@ -27,6 +27,7 @@ export type {
   DateRange,
   DateSegmentObj,
   DateSegmentPart,
+  DateStep,
   DateValue,
   DayOfWeek,
   DayPeriod,
diff --git a/packages/core/src/shared/date/types.ts b/packages/core/src/shared/date/types.ts
@@ -13,6 +13,16 @@ export type DayOfWeek = {
   daysOfWeek: (typeof daysOfWeek)[number][]
 }
 
+export type DateStep = {
+  year?: number
+  month?: number
+  day?: number
+  hour?: number
+  minute?: number
+  second?: number
+  millisecond?: number
+}
+
 export type DateRange = {
   start: DateValue | undefined
   end: DateValue | undefined
diff --git a/packages/core/src/shared/date/useDateField.ts b/packages/core/src/shared/date/useDateField.ts
@@ -1,6 +1,6 @@
 import type { CalendarDateTime, CycleTimeOptions, DateFields, DateValue, TimeFields } from '@internationalized/date'
 import type { Ref } from 'vue'
-import type { AnyExceptLiteral, HourCycle, SegmentPart, SegmentValueObj } from './types'
+import type { AnyExceptLiteral, DateStep, HourCycle, SegmentPart, SegmentValueObj } from './types'
 import type { Formatter } from '@/shared'
 import { computed } from 'vue'
 import { getDaysInMonth, toDate } from '@/date'
@@ -273,6 +273,7 @@ export type UseDateFieldProps = {
   lastKeyZero: Ref<boolean>
   placeholder: Ref<DateValue>
   hourCycle: HourCycle
+  step: Ref<DateStep>
   formatter: Formatter
   segmentValues: Ref<SegmentValueObj>
   disabled: Ref<boolean>
@@ -286,7 +287,8 @@ export function useDateField(props: UseDateFieldProps) {
   const kbd = useKbd()
 
   function minuteSecondIncrementation({ e, part, dateRef, prevValue }: MinuteSecondIncrementProps): number {
-    const sign = e.key === kbd.ARROW_UP ? 1 : -1
+    const step = props.step.value[part] ?? 1
+    const sign = e.key === kbd.ARROW_UP ? step : -step
     const min = 0
     const max = 59
 
@@ -311,7 +313,8 @@ export function useDateField(props: UseDateFieldProps) {
     return Number.parseInt(str.slice(0, -1))
   }
   function dateTimeValueIncrementation({ e, part, dateRef, prevValue, hourCycle }: DateTimeValueIncrementation): number {
-    const sign = e.key === kbd.ARROW_UP ? 1 : -1
+    const step = props.step.value[part] ?? 1
+    const sign = e.key === kbd.ARROW_UP ? step : -step
 
     if (prevValue === null)
       return dateRef[part as keyof Omit<DateFields, 'era'>]
diff --git a/packages/core/src/shared/date/utils.ts b/packages/core/src/shared/date/utils.ts
@@ -1,5 +1,6 @@
 import type { Granularity } from './comparators'
-import type { HourCycle } from './types'
+import type { DateStep, HourCycle } from './types'
+import { defu } from 'defu'
 
 export function getOptsByGranularity(granularity: Granularity, hourCycle: HourCycle, isTimeValue: boolean = false) {
   const opts: Intl.DateTimeFormatOptions = {
@@ -36,6 +37,22 @@ export function getOptsByGranularity(granularity: Granularity, hourCycle: HourCy
   return opts
 }
 
+type GetDefaultDateStepProps = {
+  step?: DateStep
+}
+
+export function normalizeDateStep(props?: GetDefaultDateStepProps): DateStep {
+  return defu(props?.step, {
+    year: 1,
+    month: 1,
+    day: 1,
+    hour: 1,
+    minute: 1,
+    second: 1,
+    millisecond: 1,
+  } satisfies DateStep)
+}
+
 export function handleCalendarInitialFocus(calendar: HTMLElement) {
   const selectedDay = calendar.querySelector<HTMLElement>('[data-selected]')
   if (selectedDay)
diff --git a/packages/core/src/shared/index.ts b/packages/core/src/shared/index.ts
@@ -2,7 +2,7 @@ export * from './arrays'
 export * from './browser'
 export * from './clamp'
 export { createContext } from './createContext'
-export { type DateRange, type DateValue } from './date'
+export { type DateRange, type DateStep, type DateValue } from './date'
 export { getActiveElement } from './getActiveElement'
 export { handleAndDispatchCustomEvent } from './handleAndDispatchCustomEvent'
 export { isValidVNodeElement } from './isValidVNodeElement'
