[SUR-747] [Improvement] - Implement Force UI Date and Time Picker for Event Schema.

[jaieds]

Summary

Adds an opt-in enableTimeSelection boolean prop (default false) to the DatePicker component, rendering time inputs between the calendar grid and the Apply/Cancel footer. This enables consumers (e.g. SureRank's Event Schema form) to replace the native browser date/time inputs with the Force UI picker.

Resolves brainstormforce/surerank#2114

Behavior

• selectionType="single": one time input that sets hours/minutes on the selected date.
• selectionType="range": start/end time inputs for from/to (end input disabled until an end date is selected).
• selectionType="multiple": the flag is ignored; no time UI is rendered.
• Times merge into the selected Date objects via date-fns setHours/setMinutes — the date portion is never replaced, and onDateSelect/onApply payloads carry the chosen time. Picking a new date preserves the previously chosen time.
• Same-day ranges are kept valid: the end can never land before the start, whether the range is completed by click or a time edit would invert it.
• With the flag off, behavior and rendered output are unchanged. No new dependencies, no changes to the existing public API.

Changes

• src/components/datepicker/datepicker.tsx — new enableTimeSelection prop, passed to all variants (normal, dualdate, presets).
• src/components/datepicker/datepicker-component.tsx — time inputs UI, time merge/preserve logic, same-day clamping.
• src/components/datepicker/utils.tsx — mergeDateTime helper.
• src/components/datepicker/datepicker.stories.tsx — three new stories with interaction (play) tests.
• src/components/datepicker/readme.md — prop documentation and usage example.

Test plan

• npm run build (tsc + vite) passes.
• ESLint clean on the datepicker directory.
• Full storybook test suite: 216 tests / 63 files, all passing.
• Interaction tests cover: disabled/enabled input states, time preservation across date picks, deselect with non-midnight times, range endpoint swap, same-day clamping, cleared-input no-op, and onDateSelect/onApply payload contents.

[github-actions]

What: Ensure proper accessibility attributes are being used for the new time input fields, such as aria-labelledby to specify labels for screen readers.

Why: Accessibility is crucial for inclusivity, allowing users with disabilities to effectively interact with your UI. Missing attributes may prevent these users from understanding and using the component correctly.

How: Add aria-labelledby attributes to the time input elements that correspond to their labels for better screen reader support.

[github-actions]

What: The new enableTimeSelection prop added to the DatePicker should have appropriate validation in the component to ensure that it only accepts boolean values. Currently, there’s a possibility that undefined or non-boolean values might be passed, leading to unpredictable behaviors.

Why: Validating prop types helps to ensure that the component behaves reliably, reducing potential runtime errors and making the component easier to debug and use. This is especially important since other developers will use this component and might not enforce these types strictly.

How: You can use PropTypes validation or TypeScript's type checking more effectively to enforce the boolean constraint. For example, use PropTypes.bool.isRequired if not using TypeScript or ensure TypeScript correctly represents this via interfaces.

[github-actions]

What: The tests extensively cover the time selection's functionality; however, there should be tests for edge cases and invalid inputs (e.g., entering invalid time strings in the time inputs).

Why: Testing for edge cases ensures that the component can gracefully handle unexpected user inputs, thereby increasing reliability and user satisfaction. It also helps prevent potential bugs from slipping into production.

How: Add additional test scenarios that simulate incorrect inputs, such as an out-of-range time (e.g., '25:00') or non-numeric strings. Confirm that the component properly handles these cases, either by maintaining current values or resetting properly.

[github-actions]

What: In the singleTimeSelectionTest, ensure you handle the possibility that the input formats could be altered or affected by localization settings. Currently, the assumptions of input formats might not hold in all environments.

Why: If the application has users in different locales, the way time is represented can vary (e.g., 12-hour vs. 24-hour formats). Failing to handle these properly could lead to incorrect data being captured or displayed, ultimately frustrating users.

How: Consider using libraries that help with localization, like date-fns, for formatting times in a way that respects user preferences. Ensure tests represent common local expectations globally.

[github-actions]

What: The implementation of the new tests is thorough, but it could benefit from additional non-happy path scenarios to check the resilience of the components against invalid props or states.

Why: Robust tests should not only cover successful use cases but also check how the component reacts in failure scenarios. This can help to ensure robustness and reliability, driving down future maintenance costs.

How: Implement tests that ensure the component fails gracefully when provided with invalid inputs and check for proper error messages or states. You can also include tests to observe performance under heavy load.

[github-actions]

What: The enableTimeSelection prop needs to be validated for boolean type before usage.

Why: Validating props helps prevent runtime errors and ensures that the component behaves as expected when incorrect data types are passed in. This is essential for maintaining the reliability and predictability of your component.

How: You can use PropTypes or TypeScript's type-checking features and consider adding a condition to handle unexpected values gracefully, such as defaulting to false if an invalid type is provided.

[github-actions]

What: Ensure that enableTimeSelection only allows boolean values (true/false).

Why: Providing a clear delineation of accepted values enhances the robustness of your component as consumers may inadvertently pass other data types which could lead to unexpected behavior.

How: You can add runtime validation in the function component like if (typeof enableTimeSelection !== 'boolean') { enableTimeSelection = false; } to enforce a boolean value.

[github-actions]

What: Consider memoizing the rendering of DatePickerComponent if the props are expensive to calculate or if they don't change often.

Why: Using React's useMemo or React.memo can prevent unnecessary re-renders of child components, thereby improving performance, especially if the DatePicker is used in a larger application with frequent updates.

How: Wrap the DatePickerComponent call inside a useMemo hook, and provide dependency arrays consisting of any props that would affect its rendering.

[github-actions]

What: Consider validating input types for the mergeDateTime function to ensure they are instances of Date.

Why: This validation will help prevent runtime errors if unexpected data types are passed to the function, improving overall stability and security of the code.

How: You can use instanceof Date to check if timeSource and date are valid date objects before proceeding with the logic. For example:

export const mergeDateTime = (date: Date, timeSource: Date | undefined) => {
    if (!(date instanceof Date) || (timeSource && !(timeSource instanceof Date))) {
        throw new Error('Invalid input: expected a Date instance.');
    }
    // existing logic... 
}```

[github-actions]

What: The mergeDateTime function may not handle cases where timeSource has invalid or non-standard date values. Consider adding a fallback mechanism.

Why: This would ensure that any invalid date inputs do not cause application crashes and maintains a seamless user experience.

How: Check if getHours and getMinutes return valid values before using them to set hours and minutes. If they return NaN or invalid values, handle them appropriately (for example, you can default these to 0):

const hours = getHours(timeSource);
const minutes = getMinutes(timeSource);
if (isNaN(hours) || isNaN(minutes)) {
    return date; // or handle differently
}
return setMinutes(setHours(date, hours), minutes);