DateTime component: Add additional design documentation and image

[cburton4]

Description

Added additional design documentation and best practices for the DateTime component. Also added an image of the component.

[benhuberman]

Hi @cburton4! I'm assuming the copy for review is what's in the Files changed tab, but let me know if I missed something! Here are a few small tweaks I'd propose there:

Before:

a React component to render a calendar and clock for selecting a date and time

After:

a React component that renders a calendar and clock for date and time selection.

Before:

Use smart defaults and highlight that day’s date.

After:

Use smart defaults and highlight the current date.

Before:

Not be used to enter a date that is many years in the future or the past.

After:

Prevent the ability to enter dates in the distant future or past.

For the last point, if there's a consensus around what qualifies as "many years" or "distant" (One year? Three? Ten?) that would be a lot more useful, I think, as people's notions of the distant future/past depend on so many personal and cultural variables.

[cburton4]

@benhuberman

Thank you for this feedback. Love these tweaks.

For distant future or past I updated to:

Prevent the ability to enter dates more than a year in the future or past.

I wouldn't say there is consensus on this though. Open to any other suggestions here on what makes sense to other folks.

[davewhitley]

Not be used to enter a date that is many years in the future or the past.

I could be wrong, but I don't think it's about preventing that. I interpreted that line like the component just isn't designed to enter a date that is far in the future/past. For example, in order to select a date far into the future/past you would have to click a lot to get to the year you need. The better alternative is to enter the date into a text input field. Although, this component does have text input fields as a secondary way to select a date so maybe this guideline is irrelevant.

[cburton4]

Not be used to enter a date that is many years in the future or the past.

I could be wrong, but I don't think it's about preventing that. I interpreted that line like the component just isn't designed to enter a date that is far in the future/past. For example, in order to select a date far into the future/past you would have to click a lot to get to the year you need. The better alternative is to enter the date into a text input field. Although, this component does have text input fields as a secondary way to select a date so maybe this guideline is irrelevant.

Yep, I think you're right. I'll remove this guideline.

[youknowriad]

Isn't this a behavior that is already absorbed by the component itself? Is it worth adding to the docs? A user might ask "how do I do that" since it's mentioned in the "best practices"?

[cburton4]

I see where you're coming from. The idea behind documenting this is to help define the best practices for a component like this in terms of functionality. I think it's useful in case folks in the future want to make an update to this component that might affect this functionality as well as a precedent in case future folks want to make a new component that has similar functionality.