Date Picker element

[Westbrook]

Moving some discussion around developing the Date Picker, and its various subelements, here so it's easier to track.

Right now, @paulodetarsofm is leading development here, but hopefully all of us in the community can support making this pattern high quality and robust.

[Westbrook]

From Paulo:

1. Internationalisation: how should I translate the elements that make up the calendar? I'll use the Intl.DateTimeFormat for the names of the months and the days of the week, but what about the button titles like "Previous" and "Next" and any other textual elements that might exist?

[Westbrook]

Fastest/easiest isn't always right and complete. If you chose to use properties for all these values you're looking at an API in the realm of:

<sp-calendar
  label-next=${textValueForLabbellingTheNextButton}
  label-previous=${textValueForLabbellingThePreviousButton}
  text-today=${textValueForOutliningToday}
  text-selected=${textValueForOutliningSelected}
  // etc.
></sp-calendar>

It's faster because it doesn't involve extra tools, but as the Shoelace docs point out it can get quite complex. You could take an intermediary translations object, a la:

<sp-calendar
  .textContent=${{
    next: textValueForLabbellingTheNextButton,
    previous: textValueForLabbellingThePreviousButton,
    today: textValueForOutliningToday,
    selected: textValueForOutliningSelected,
    // ... etc.
  }}
></sp-calendar>

Which isn't that different, but could be seen as easier to manage. This starts to look like Shoelace, but with less features, however.

A more advanced pattern, but one that puts a lot more responsibility on the consumer in this case, would be to use slots:

<sp-calendar>
    <template shadowrootmode="open">
        <!-- other things -->
        <slot
            name="next-button"
            @click=${...}
            @other-required-bindings=${...}
         >
            <sp-action-button>Next</sp-action-button> <!-- Default slot content is English -->
        </slot>
        <!-- other things --->
    </template>
    <sp-action-button slot="next-button">すぎの月<sp-action-button> <!-- provided content is Japanese -->
</sp-calendar>

This is also possible with a more XML like API, with a lower level of overall customization, but a stricter adherence to "Spectrum":

<sp-calendar>
    <template shadowrootmode="open">
        <!-- other things -->
        <sp-action-button
            @click=${...}
            @other-required-bindings=${...}
        >
            <slot name="next-button">
                Next <!-- Default slot text is English -->
             </slot>
        </sp-action-button> 
        </slot>
        <!-- other things --->
    </template>
    <span slot="next-button">すぎの月<span> <!-- provided content is Japanese -->
</sp-calendar>

[paulodetarsofm]

I like the last example, I'll implement it that way, but what about the "title", which has words that need to be translated plus the date that will already be formatted correctly by the Intl.DateTimeFormat? They are texts that will be used as an attribute value, they won't be used individually and directly in the component

[Westbrook]

I think you mean text like Today, Sunday, July 30, 2017 selected, which would be "${this.textToday}, ${this.intlProcessedDate} ${this.textSelected}", but I'm not sure what you mean by:

They are texts that will be used as an attribute value, they won't be used individually and directly in the component

[paulodetarsofm]

I meant that in your last example the texts would be provided using slots, but how would I use the text of a slot as part of a "title" attribute? Won't the slot content be the tag content? How can I use this "Next" text as part of the "title"?

BTW, in the HTML markup available in Calendar CSS the buttons don't have a label, just an icon as part of the content, and the texts are applied to "title" and "aria-label".

Also, I didn't understand how to use two slots with the same name, <span slot="next-button">, but with different contents. The first one is inside a <template shadowrootmode="open"> tag, which I don't know, but how would my component know to identify which slot should be used?

[Westbrook]

I see. title is not often really what we mean to use here. When applying an accessible label aria-label (which also won’t accessor slotted values) or aria-labelledby (which can) is always better. It’s likely that the CSS version leverages title but let’s lean away from that as much as possible, even if the use of attributes over slots leaves that door open to you.

<template shadowrootmode="open"> is used here only as declarative shorthand for “what’s in the shadow root”. In that way, I’m not sure I see the two slots you’ve noted here. A <slot> element demarcates where the content can be projected from the outside, while accepting default content directly within it, and the slot=“…” attribute outlines content that will be projected on that slot. From the outside we can technically address as much content as we’d like to any of the slots that are surfaced, but I’m not sure that will be needed in this case.

[Westbrook]

From Paulo:

3. Although initially I won't include support for other types of calendars, I saw that in the React component there are several files/classes that make up the calendar. Do you think it's a good idea to try to bring this content here too? The only problem is that the parts involving React I can't understand, but the generic functions do, so if we're going to reuse some things from this calendar component created with React maybe I need help with that 🙃

[Westbrook]

What sort of "other calendars" does React support? Do you need them for the initial shipment of this component? As long as there's a little thought put into how we might add them later, maybe we don't need to bloat the scope of an initial release? Generally, I'm not sure there's much to be reused, code wise, from the React implementation as it is quite tightly bound to the reality of rendering in React.

[Westbrook]

From Paulo:

3. See below for "other calendars" that the React component supports. Really, for an early release, I don't see the need to include support for other calendars, but it would be nice to know if what was done in this React release would be something we could repurpose or not
   image.png

[Westbrook]

In theory if you use this library (of data, rather than UI), as implied in this comment, then you should have access to this data when we are ready to leverage it. Whether that in an initial release or follow up work.

[Westbrook]

From Paulo:

I saw somewhere this link: Spectrum Contributions - Date picker. Can anyone tell me what this would be exactly and if it's something I should "worry about"/use?

[Westbrook]

The links in that documentation point to the Spectrum CSS implementation that you are leveraging here, so I don't think there are any issues there. Might be a good thing to ensure you design team is talking with the Spectrum team, as well.

[Westbrook]

From Paulo:

How do I get the Express styles for the calendar? Or have these styles not been created yet?

[Westbrook]

Anything that has Express styles get them from Spectrum CSS by default. It may be important to link you designers with the Spectrum team and let them know that there is extended need for this pattern, in the case that they think it is not "Express-ified".

[paulodetarsofm]

In the Calendar CSS page, the buttons in the header of the calendar, when disabled, have some styles applied, however, in the web component these styles no longer exist in spectrum-calendar.css and the styles of sp-action-button disabled are being overwritten, and as a result, the button doesn't look disabled. What should I do?

[Westbrook]

You’re adding the disabled attribute to these buttons in this case?

[ninavizz]

Hello! A team I'm working with is seeking to adopt the Spectrum components library, however our needs with a date range picker are unique. Unlike "reservation" type apps, our users' most common need involves selecting dates across multiple years; and they're older users, so "oddball" interaction patterns, cumbersome discoverability, small click targets, and showy animations, are off the table.

I designed this picker for our users, largely picking-up what Stripe has done in their dashboard experience for backstage users. I like its clarity and simplicity a lot, that it better meets the needs of motor-skills impaired users, and that Stripe has already done user testing to inform the design solution itself, has me confident in its usability.

What my team does not have, is a FE developer. I wanted to share this, here, to see if there might be any interest among the community in building/adding it into the Spectrum system?