Merge branch 'next' into calendar

docs/pages/components/calendar.md

@@ -0,0 +1,67 @@
+---
+meta:
+  title: Calendar
+  description: Calendar shows a monthly view of the Gregorian calendar, optionally allowing users to interact with dates.
+layout: component
+---
+
+```html:preview
+<sl-calendar></sl-calendar>
+```
+
+## Examples
+
+### Month & Day Labels
+
+Month and day labels can be customized using the `month-labels` and `day-labels` attributes. Note that month names are localized automatically based on the component's `lang` attribute, falling back to the document language.
+
+```html:preview
+<sl-calendar month-labels="short" day-labels="narrow"></sl-calendar>
+```
+
+### Showing Adjacent Dates
+
+By default, only dates in the target month are shown. You can fill the grid with adjacent dates using the `show-adjacent-dates` attribute.
+
+```html:preview
+<sl-calendar show-adjacent-dates></sl-calendar>
+```
+
+### Date Selection
+
+One or more dates can be selected by setting the `selectedDates` property. An array of dates is accepted and the selection does not have to be continuous.
+
+```html:preview
+<sl-calendar class="calendar-selection"></sl-calendar>
+
+<script>
+  const calendar = document.querySelector('.calendar-selection');
+  const today = new Date();
+
+  // Set the selected date range from the 12-15 of the current month
+  calendar.selectedDates = [
+    new Date(today.getFullYear(), today.getMonth(), 12),
+    new Date(today.getFullYear(), today.getMonth(), 13),
+    new Date(today.getFullYear(), today.getMonth(), 14),
+    new Date(today.getFullYear(), today.getMonth(), 15)
+  ];
+</script>
+```
+
+### With Borders
+
+To add a border, set the `--border-width` custom property. You can further customize the border with `--border-color` and `--border-radius`.
+
+```html:preview
+<sl-calendar style="--border-width: 1px;"></sl-calendar>
+```
+
+### Localizing the Calendar
+
+By default, the calendar will use the document's locale. You can use the `lang` attribute to change this.
+
+```html:preview
+<sl-calendar lang="es"></sl-calendar>
+```
+
+[component-metadata:sl-calendar]

src/components/calendar/calendar.component.ts

@@ -0,0 +1,204 @@
+import { classMap } from 'lit/directives/class-map.js';
+import { generateCalendarGrid, getAllDayNames, getMonthName, isSameDay } from '../../internal/calendar.js';
+import { HasSlotController } from '../../internal/slot.js';
+import { html } from 'lit';
+import { LocalizeController } from '../../utilities/localize.js';
+import { partMap } from '../../internal/part-map.js';
+import { property } from 'lit/decorators.js';
+import { watch } from '../../internal/watch.js';
+import ShoelaceElement from '../../internal/shoelace-element.js';
+import styles from './calendar.styles';
+import type { CSSResultGroup, TemplateResult } from 'lit';
+
+export interface RenderDayOptions {
+  disabled?: boolean;
+  content: string | TemplateResult;
+}
+
+/**
+ * @summary A calendar prototype for Shoelace.
+ * @documentation https://shoelace.style/components/calendar
+ *
+ * @since 2.0
+ * @status experimental
+ *
+ * @dependency sl-example
+ *
+ * @event sl-change - Emitted when the date changes.
+ *
+ * @slot footer - Optional content to place in the calendar's footer.
+ *
+ * @csspart day - Targets day cells.
+ * @csspart day-label - Targets the day labels (the name of the days in the grid).
+ * @csspart day-weekend - Targets days that fall on weekends.
+ * @csspart day-weekday - Targets weekdays.
+ * @csspart day-current-month - Targets days in the current month.
+ * @csspart day-previous-month - Targets days in the previous month.
+ * @csspart day-next-month - Targets days in the next month.
+ * @csspart day-today - Targets today.
+ * @csspart day-selected - Targets selected days.
+ * @csspart day-selection-start - Targets days that begin a selection.
+ * @csspart day-selection-end - Targets days that end a selection.
+ *
+ * @cssproperty --border-color - The calendar's border color.
+ * @cssproperty --border-width - The calendar's border width.
+ * @cssproperty --border-radius - The border radius of the calendar.
+ */
+export default class SlCalendar extends ShoelaceElement {
+  static styles: CSSResultGroup = styles;
+
+  private readonly localize = new LocalizeController(this);
+  private readonly hasSlotController = new HasSlotController(this, 'prefix', 'suffix');
+
+  /** The month to render, 1-12/ */
+  @property({ type: Number, reflect: true }) month: number = new Date().getMonth() + 1;
+
+  /** The year to render. */
+  @property({ type: Number, reflect: true }) year: number = new Date().getFullYear();
+
+  /** Determines how day labels are shown, e.g. "M", "Mon", or "Monday". */
+  @property({ attribute: 'day-labels' }) dayLabels: 'narrow' | 'short' | 'long' = 'short';
+
+  /** Determines how month labels are shown, e.g. "J", "Jan", or "January". */
+  @property({ attribute: 'month-labels' }) monthLabels: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow' = 'long';
+
+  /** When true, dates from the previous and next month will also be shown to fill out the grid. */
+  @property({ attribute: 'show-adjacent-dates', type: Boolean }) showAdjacentDates = false;
+
+  /** Draws the target dates as a selection in the calendar. */
+  @property({ type: Array }) selectedDates: Date[] = [];
+
+  /** Moves the calendar to the current month and year. */
+  goToToday() {
+    this.month = new Date().getMonth() + 1;
+    this.year = new Date().getFullYear();
+  }
+
+  /** Moves the calendar to the previous month. */
+  goToPreviousMonth() {
+    if (this.month === 1) {
+      this.month = 12;
+      this.year--;
+    } else {
+      this.month--;
+    }
+  }
+
+  /** Moves the calendar to the next month. */
+  goToNextMonth() {
+    if (this.month === 12) {
+      this.month = 1;
+      this.year++;
+    } else {
+      this.month++;
+    }
+  }
+
+  @watch('month')
+  @watch('year')
+  handleMonthChange() {
+    this.emit('sl-change');
+  }
+
+  render() {
+    if (this.month < 1 || this.month > 12) {
+      throw new Error(`The value "${this.month}" is not a valid month.`);
+    }
+
+    const lang = this.lang || document.documentElement.lang;
+    const month = new Date(this.year, this.month - 1, 1);
+    const dayGrid = generateCalendarGrid(this.year, this.month);
+    const dayNames = getAllDayNames(lang, this.dayLabels);
+
+    //
+    // TODO - December is not showing a label because the month is calculated as Sat Jan 01 2022 00:00:00 GMT-0500
+    //
+
+    return html`
+      <div
+        class=${classMap({
+          calendar: true,
+          'calendar--has-footer': this.hasSlotController.test('footer'),
+          'calendar--show-adjacent-dates': this.showAdjacentDates
+        })}
+      >
+        <header class="calendar__header">
+          <sl-icon-button
+            name="chevron-left"
+            label=${this.localize.term('previousMonth')}
+            @click=${this.goToPreviousMonth}
+          ></sl-icon-button>
+
+          <span class="calendar__label">
+            <span class="calendar__month-label">${getMonthName(month, lang, this.monthLabels)}</span>
+            <span class="calendar__year-label">${month.getFullYear()}</span>
+          </span>
+
+          <sl-icon-button
+            name="chevron-right"
+            label=${this.localize.term('nextMonth')}
+            @click=${this.goToNextMonth}
+          ></sl-icon-button>
+        </header>
+
+        <div class="calendar__days">
+          ${[0, 1, 2, 3, 4, 5, 6].map(day => {
+            return html`
+              <span
+                part=${partMap({
+                  day: true,
+                  'day-label': true,
+                  'day-weekday': day > 0 && day < 6,
+                  'day-weekend': day === 0 || day === 6
+                })}
+                class="calendar__day"
+              >
+                ${dayNames[day]}
+              </span>
+            `;
+          })}
+          ${dayGrid.map((day, index) => {
+            if (day.isCurrentMonth || this.showAdjacentDates) {
+              const isSelected = Array.isArray(this.selectedDates)
+                ? this.selectedDates.some(d => isSameDay(d, day.date))
+                : false;
+              const previousDay = index > 0 ? dayGrid[index - 1] : null;
+              const nextDay = index < dayGrid.length - 1 ? dayGrid[index + 1] : null;
+              const isSelectionStart =
+                isSelected && previousDay ? !this.selectedDates.some(d => isSameDay(d, previousDay.date)) : false;
+              const isSelectionEnd =
+                isSelected && nextDay ? !this.selectedDates.some(d => isSameDay(d, nextDay.date)) : false;
+
+              return html`
+                <button
+                  type="button"
+                  part=${partMap({
+                    day: true,
+                    'day-current-month': day.isCurrentMonth,
+                    'day-previous-month': day.isPreviousMonth,
+                    'day-next-month': day.isNextMonth,
+                    'day-today': day.isToday,
+                    'day-weekday': day.isWeekday,
+                    'day-weekend': day.isWeekend,
+                    'day-selected': isSelected,
+                    'day-selection-start': isSelectionStart,
+                    'day-selection-end': isSelectionEnd
+                  })}
+                  class="calendar__day"
+                >
+                  ${day.date.getDate()}
+                </button>
+              `;
+            }
+
+            return html` <div class="calendar__day calendar__day--empty"></div> `;
+          })}
+        </div>
+
+        <footer class="calendar__footer">
+          <slot name="footer"></slot>
+        </footer>
+      </div>
+    `;
+  }
+}

src/components/calendar/calendar.styles.ts

@@ -0,0 +1,119 @@
+import { css } from 'lit';
+import componentStyles from '../../styles/component.styles';
+
+export default css`
+  ${componentStyles}
+
+  :host {
+    --border-color: var(--sl-color-neutral-200);
+    --border-radius: var(--sl-border-radius-medium);
+    --border-width: 0;
+
+    display: block;
+  }
+
+  .calendar__header {
+    display: flex;
+    align-items: center;
+    margin-bottom: var(--sl-spacing-x-small);
+  }
+
+  .calendar__header sl-icon-button {
+    flex: 0 0 auto;
+  }
+
+  .calendar__label {
+    flex: 1 1 auto;
+    text-align: center;
+  }
+
+  .calendar__days {
+    isolation: isolate;
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+  }
+
+  .calendar__day {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+    border: solid var(--border-width) var(--border-color);
+    border-bottom: none;
+    background: none;
+    background-color: var(--sl-color-neutral-0);
+    font: inherit;
+    color: var(--sl-color-neutral-900);
+    min-height: 3rem;
+    padding: 0;
+    margin: 0;
+  }
+
+  .calendar__day:nth-child(1) {
+    border-top-left-radius: var(--border-radius);
+  }
+
+  .calendar__day:nth-child(7) {
+    border-top-right-radius: var(--border-radius);
+  }
+
+  .calendar__day:nth-last-child(1) {
+    border-bottom-right-radius: var(--border-radius);
+  }
+
+  .calendar__day:nth-last-child(7) {
+    border-bottom-left-radius: var(--border-radius);
+  }
+
+  .calendar__day:not(:nth-child(7n)) {
+    border-right: none;
+  }
+
+  .calendar__day:nth-last-child(1),
+  .calendar__day:nth-last-child(2),
+  .calendar__day:nth-last-child(3),
+  .calendar__day:nth-last-child(4),
+  .calendar__day:nth-last-child(5),
+  .calendar__day:nth-last-child(6),
+  .calendar__day:nth-last-child(7) {
+    border-bottom: solid var(--border-width) var(--border-color);
+  }
+
+  .calendar__day:focus-visible {
+    outline: solid 2px var(--sl-color-primary-600);
+    z-index: 1;
+  }
+
+  .calendar__day[part~='day-weekend'] {
+    color: var(--sl-color-rose-600);
+  }
+
+  .calendar__day[part~='day-today'] {
+    font-weight: var(--sl-font-weight-bold);
+  }
+
+  .calendar__day[part~='day-selected'] {
+    background-color: var(--sl-color-primary-100);
+  }
+
+  .calendar__day[part~='day-selection-start'] {
+    border-top-left-radius: var(--sl-border-radius-pill);
+    border-bottom-left-radius: var(--sl-border-radius-pill);
+  }
+
+  .calendar__day[part~='day-selection-end'] {
+    border-top-right-radius: var(--sl-border-radius-pill);
+    border-bottom-right-radius: var(--sl-border-radius-pill);
+  }
+
+  .calendar__day .calendar__day[part~='day-previous-month'],
+  .calendar__day[part~='day-next-month'] {
+    color: var(--sl-color-neutral-400);
+  }
+
+  .calendar__day[part~='day-previous-month'][part~='day-weekend'],
+  .calendar__day[part~='day-next-month'][part~='day-weekend'] {
+    color: var(--sl-color-rose-400);
+  }
+`;

src/components/calendar/calendar.test.ts

@@ -0,0 +1,9 @@
+import { expect } from '@open-wc/testing';
+
+describe('<sl-calendar>', () => {
+  it('should render a component', async () => {
+    // const el = await fixture(html` <sl-calendar></sl-calendar> `);
+    const a = true;
+    expect(a).to.be.true;
+  });
+});

src/components/calendar/calendar.ts

@@ -0,0 +1,12 @@
+import SlCalendar from './calendar.component.js';
+
+export * from './calendar.component.js';
+export default SlCalendar;
+
+SlCalendar.define('sl-calendar');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'sl-calendar': SlCalendar;
+  }
+}

src/internal/calendar.ts

@@ -0,0 +1,141 @@
+export interface CalendarDay {
+  date: Date;
+  isToday: boolean;
+  isWeekday: boolean;
+  isWeekend: boolean;
+  isCurrentMonth: boolean;
+  isPreviousMonth: boolean;
+  isNextMonth: boolean;
+}
+
+export interface CalendarGridOptions {
+  weekStartsWith: 'sunday' | 'monday';
+}
+
+/** Generates a calendar grid. Month should be 1-12, not 0-11. */
+export function generateCalendarGrid(year: number, month: number, options?: Partial<CalendarGridOptions>) {
+  const weekStartsWith = options?.weekStartsWith || 'sunday';
+  const today = new Date();
+  const dayThisMonthStartsWith = new Date(year, month - 1, 1).getDay();
+  const lastDayOfMonth = new Date(year, month, 0).getDate();
+  const lastDayOfPreviousMonth =
+    month === 1 ? new Date(year - 1, 1, 0).getDate() : new Date(year, month - 1, 0).getDate();
+  const dayGrid: CalendarDay[] = [];
+  let day = 1;
+
+  do {
+    const date = new Date(year, month - 1, day);
+    let dayOfWeek = new Date(year, month - 1, day).getDay();
+
+    if (weekStartsWith === 'sunday') {
+      //
+      // TODO
+      //
+    }
+
+    // Days in the previous month
+    if (day === 1) {
+      let lastMonthDay = lastDayOfPreviousMonth - dayThisMonthStartsWith + 1;
+      for (let i = 0; i < dayThisMonthStartsWith; i++) {
+        const dayOfLastMonth = new Date(year, month - 2, lastMonthDay);
+
+        dayGrid.push({
+          date: dayOfLastMonth,
+          isToday: isSameDay(dayOfLastMonth, today),
+          isWeekday: isWeekday(dayOfLastMonth),
+          isWeekend: isWeekend(dayOfLastMonth),
+          isCurrentMonth: false,
+          isPreviousMonth: true,
+          isNextMonth: false
+        });
+
+        lastMonthDay++;
+      }
+    }
+
+    dayGrid.push({
+      date,
+      isToday: isSameDay(date, today),
+      isWeekday: isWeekday(date),
+      isWeekend: isWeekend(date),
+      isCurrentMonth: true,
+      isPreviousMonth: false,
+      isNextMonth: false
+    });
+
+    // Days in the next month
+    if (day === lastDayOfMonth) {
+      let nextMonthDay = 1;
+      for (dayOfWeek; dayOfWeek < 6; dayOfWeek++) {
+        const dayOfNextMonth = new Date(year, month, nextMonthDay);
+
+        dayGrid.push({
+          date: dayOfNextMonth,
+          isToday: isSameDay(dayOfNextMonth, today),
+          isWeekday: isWeekday(dayOfNextMonth),
+          isWeekend: isWeekend(dayOfNextMonth),
+          isCurrentMonth: false,
+          isPreviousMonth: false,
+          isNextMonth: true
+        });
+
+        nextMonthDay++;
+      }
+    }
+
+    day++;
+  } while (day <= lastDayOfMonth);
+
+  return dayGrid;
+}
+
+/** Generates a localized array of day names. */
+export function getAllDayNames(locale = 'en', format: Intl.DateTimeFormatOptions['weekday'] = 'long') {
+  const formatter = new Intl.DateTimeFormat(locale, { weekday: format, timeZone: 'UTC' });
+  const days = [1, 2, 3, 4, 5, 6, 7].map(day => {
+    const dd = day < 10 ? `0${day}` : day;
+    return new Date(`2017-01-${dd}T00:00:00+00:00`);
+  });
+  return days.map(date => formatter.format(date));
+}
+
+/** Generates a localized array of month names. */
+export function getAllMonthNames(locale = 'en', format: Intl.DateTimeFormatOptions['month'] = 'long') {
+  const formatter = new Intl.DateTimeFormat(locale, { month: format, timeZone: 'UTC' });
+  const months = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].map(month => {
+    const mm = month < 10 ? `0${month}` : month;
+    return new Date(`2017-${mm}-01T00:00:00+00:00`);
+  });
+  return months.map(date => formatter.format(date));
+}
+
+/** Determines if two dates are the same day. */
+export function isSameDay(date1: Date, date2: Date) {
+  return (
+    date1.getFullYear() === date2.getFullYear() &&
+    date1.getMonth() === date2.getMonth() &&
+    date1.getDate() === date2.getDate()
+  );
+}
+
+/** Determines if the date is a weekend. */
+export function isWeekend(date: Date) {
+  const day = date.getDay();
+  return day === 0 || day === 6;
+}
+
+/** Determines if the date is a weekday. */
+export function isWeekday(date: Date) {
+  const day = date.getDay();
+  return day > 0 && day < 6;
+}
+
+/** Returns a localized, human-readable day name. */
+export function getDayName(date: Date, locale = 'en', format: Intl.DateTimeFormatOptions['weekday'] = 'long') {
+  return getAllDayNames(locale, format)[date.getDate() - 1];
+}
+
+/** Returns a localized, human-readable month name. */
+export function getMonthName(date: Date, locale = 'en', format: Intl.DateTimeFormatOptions['month'] = 'long') {
+  return getAllMonthNames(locale, format)[date.getMonth()];
+}

src/internal/part-map.ts

@@ -0,0 +1,11 @@
+export function partMap(map: { [partName: string]: boolean }) {
+  const parts = [];
+
+  for (const [key, value] of Object.entries(map)) {
+    if (value) {
+      parts.push(key);
+    }
+  }
+
+  return parts.join(' ');
+}

src/shoelace.ts

@@ -8,6 +8,7 @@ export { default as SlBreadcrumb } from './components/breadcrumb/breadcrumb.js';
 export { default as SlBreadcrumbItem } from './components/breadcrumb-item/breadcrumb-item.js';
 export { default as SlButton } from './components/button/button.js';
 export { default as SlButtonGroup } from './components/button-group/button-group.js';
+export { default as SlCalendar } from './components/calendar/calendar.js';
 export { default as SlCard } from './components/card/card.js';
 export { default as SlCarousel } from './components/carousel/carousel.js';
 export { default as SlCarouselItem } from './components/carousel-item/carousel-item.js';

src/translations/en.ts

@@ -16,12 +16,14 @@ const translation: Translation = {
   goToSlide: (slide, count) => `Go to slide ${slide} of ${count}`,
   hidePassword: 'Hide password',
   loading: 'Loading',
+  nextMonth: 'Next month',
   nextSlide: 'Next slide',
   numOptionsSelected: num => {
     if (num === 0) return 'No options selected';
     if (num === 1) return '1 option selected';
     return `${num} options selected`;
   },
+  previousMonth: 'Previous month',
   previousSlide: 'Previous slide',
   progress: 'Progress',
   remove: 'Remove',

src/utilities/localize.ts

@@ -23,8 +23,10 @@ export interface Translation extends DefaultTranslation {
   goToSlide: (slide: number, count: number) => string;
   hidePassword: string;
   loading: string;
+  nextMonth?: string; // TODO - add to other language packs and remove optional ? flag
   nextSlide: string;
   numOptionsSelected: (num: number) => string;
+  previousMonth?: string; // TODO - add to other language packs and remove optional ? flag
   previousSlide: string;
   progress: string;
   remove: string;