Skip to content

Latest commit

 

History

History
479 lines (379 loc) · 20.1 KB

README.md

File metadata and controls

479 lines (379 loc) · 20.1 KB
Raw

dayzed

Primitives to build simple, flexible, WAI-ARIA compliant React date-picker components.

version MIT License All Contributors

Supports React and Preact size gzip size module formats: umd, cjs, and es

The problem

You need a date-picker in your application that is accessible, can fit a number of use cases (single date, multi date, range), and has styling and layout that can be easily extended.

This solution

This is a component that focuses on controlling user interactions so you can focus on creating beautiful, accessible, and useful date-pickers. It uses a custom Hook or a render function as children. This means you are responsible for rendering everything, but props are provided by the Hook or render function, through a pattern called prop getters, which can be used to help enhance what you are rendering.

This differs from other solutions which render things for their use case and then expose many options to allow for extensibility resulting in a bigger API that is less flexible as well as making the implementation more complicated and harder to contribute to.

Table of Contents

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:

npm install --save dayzed

Or, you can install this module through the yarn package manager.

yarn add dayzed

This package also depends on react@>=16.8.0 and prop-types. Please make sure you have those installed as well.

Note also this library supports preact@>=10 out of the box. If you are using preact then use the corresponding module in the preact/dist folder. You can even import Dayzed from 'dayzed/preact' or import { useDayzed } from 'dayzed/preact'

Usage

import React from 'react';
import Dayzed, { useDayzed } from 'dayzed';

const monthNamesShort = [
  'Jan',
  'Feb',
  'Mar',
  'Apr',
  'May',
  'Jun',
  'Jul',
  'Aug',
  'Sep',
  'Oct',
  'Nov',
  'Dec'
];
const weekdayNamesShort = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];

function Calendar({ calendars, getBackProps, getForwardProps, getDateProps }) {
  if (calendars.length) {
    return (
      <div style={{ maxWidth: 800, margin: '0 auto', textAlign: 'center' }}>
        <div>
          <button {...getBackProps({ calendars })}>Back</button>
          <button {...getForwardProps({ calendars })}>Next</button>
        </div>
        {calendars.map(calendar => (
          <div
            key={`${calendar.month}${calendar.year}`}
            style={{
              display: 'inline-block',
              width: '50%',
              padding: '0 10px 30px',
              boxSizing: 'border-box'
            }}
          >
            <div>
              {monthNamesShort[calendar.month]} {calendar.year}
            </div>
            {weekdayNamesShort.map(weekday => (
              <div
                key={`${calendar.month}${calendar.year}${weekday}`}
                style={{
                  display: 'inline-block',
                  width: 'calc(100% / 7)',
                  border: 'none',
                  background: 'transparent'
                }}
              >
                {weekday}
              </div>
            ))}
            {calendar.weeks.map((week, weekIndex) =>
              week.map((dateObj, index) => {
                let key = `${calendar.month}${calendar.year}${weekIndex}${index}`;
                if (!dateObj) {
                  return (
                    <div
                      key={key}
                      style={{
                        display: 'inline-block',
                        width: 'calc(100% / 7)',
                        border: 'none',
                        background: 'transparent'
                      }}
                    />
                  );
                }
                let { date, selected, selectable, today } = dateObj;
                let background = today ? 'cornflowerblue' : '';
                background = selected ? 'purple' : background;
                background = !selectable ? 'teal' : background;
                return (
                  <button
                    style={{
                      display: 'inline-block',
                      width: 'calc(100% / 7)',
                      border: 'none',
                      background
                    }}
                    key={key}
                    {...getDateProps({ dateObj })}
                  >
                    {selectable ? date.getDate() : 'X'}
                  </button>
                );
              })
            )}
          </div>
        ))}
      </div>
    );
  }
  return null;
}

/*----------- Render Prop -----------*/

class Datepicker extends React.Component {
  render() {
    return (
      <Dayzed
        onDateSelected={this.props.onDateSelected}
        selected={this.props.selected}
        render={dayzedData => <Calendar {...dayzedData} />}
      />
    );
  }
}

///////////////////////////////////////
// OR
///////////////////////////////////////

/*----------- Custom Hook -----------*/

function Datepicker(props) {
  let dayzedData = useDayzed(props);
  return <Calendar {...dayzedData} />;
}

class Single extends React.Component {
  state = { selectedDate: null };

  _handleOnDateSelected = ({ selected, selectable, date }) => {
    this.setState(state => ({ selectedDate: date }));
  };

  render() {
    let { selectedDate } = this.state;
    return (
      <div>
        <Datepicker
          selected={this.state.selectedDate}
          onDateSelected={this._handleOnDateSelected}
        />
        {this.state.selectedDate && (
          <div style={{ paddingTop: 20, textAlign: 'center' }}>
            <p>Selected:</p>
            <p>{`${selectedDate.toLocaleDateString()}`}</p>
          </div>
        )}
      </div>
    );
  }
}

export default Single;

Props

date

date | defaults to new Date()

Used to calculate what month to display on initial render.

maxDate

date | optional

Used to calculate the maximum month to render.

minDate

date | optional

Used to calculate the minimum month to render.

monthsToDisplay

number | defaults to 1

Number of months returned, based off the date and offset props.

firstDayOfWeek

number | defaults to 0

First day of the week with possible values 0-6 (Sunday to Saturday). Defaults to Sunday.

showOutsideDays

boolean | defaults to false

Flag to fill front and back weeks with dates from adjacent months.

selected

any | optional

An array of Dates or a single Date that has been selected.

onDateSelected

function(selectedDate: Date, event: Event) | required

Called when the user selects a date.

  • selectedDate: The date that was just selected.
  • event: The event fired when the date was selected.

render

function({}) | required

This is called with an object. Read more about the properties of this object in the section "Render Prop Function".

offset

number | control prop (read more about this in the "Control Props" section below) - defaults to 0 if not controlled.

Number off months to offset from the date prop.

onOffsetChanged

function(offset: number) | control prop (read more about this in the "Control Props" section below)

Called when the user selects to go forward or back. This function is required if offset is being provided as a prop.

  • offset: The number of months offset.

Control Props

dayzed manages its own offset state internally and calls your onOffsetChanged handler when the offset changes. Your render prop function (read more below) can be used to manipulate this state from within the render function and can likely support many of your use cases.

However, if more control is needed, you can pass offset as a prop (as indicated above) and that state becomes controlled. As soon as this.props.offset !== undefined, internally, dayzed will determine its state based on your prop's value rather than its own internal state. You will be required to keep the state up to date (this is where the onOffsetChanged handler comes in really handy), but you can also control the state from anywhere, be that state from other components, redux, react-router, or anywhere else.

Note: This is very similar to how normal controlled components work elsewhere in react (like <input />). If you want to learn more about this concept, you can learn about that from this the "Controlled Components" lecture

Custom Hook

You can either use the custom useDayzed hook or the render prop function (described in the section below) to return the things needed to render your calendars. The custom Hook has a benefit over the render prop function as it does not unnecessarily add an additional child into the render tree. Example:

function Datepicker(props) {
  let { calendars, getBackProps, getForwardProps, getDateProp } = useDayzed(
    props
  );
  return <div>{/* calendar elements */}</div>;
}

Render Prop Function

This is where you render whatever you want to based on the state of dayzed. It's a regular prop called render: <Dayzed render={/* right here*/} />.

You can also pass it as the children prop if you prefer to do things that way <Dayzed>{/* right here*/}</Dayzed>

Fun fact, the Dazyed render prop component actually uses the useDayzed custom Hook under the hood.

The properties of this object can be split into two categories as indicated below:

prop getters

See the blog post about prop getters

These functions are used to apply props to the elements that you render. This gives you maximum flexibility to render what, when, and wherever you like. You call these on the element in question (for example: <button {...getDateProps()})). It's advisable to pass all your props to that function rather than applying them on the element yourself to avoid your props being overridden (or overriding the props returned). For example: getDateProps({onClick(event) {console.log(event)}}).

property type description
getDateProps function({}) Returns the props you should apply to the date button elements you render.
getBackProps function({}) Returns the props you should apply to any back button element you render.
getForwardProps function({}) Returns the props you should apply to any forward button element you render.

state

These are values that represent the current state of the dayzed component.

property type description
calendars any An array containing objects of each month's data.
calendars[{}].month number Zero-based number of the month. (0 - 11)
calendars[{}].year number The year of the month.
calendars[{}].firstDayOfMonth date First day of the month.
calendars[{}].lastDayOfMonth date Last day of the month.
calendars[{}].weeks any An array containing an array of date objects for each week of the month. Starting from Sunday to Saturday. [ ["", "", "", "", dateObj, dateObj, dateObj] ]
calendars[{}].weeks[[{}]].date date A Date object for that day of the week.
calendars[{}].weeks[[{}]].selected boolean Whether the Date was given as part of the provided selected prop.
calendars[{}].weeks[[{}]].selectable boolean Whether the Date is selectable given the provided maxDate and minDate props.
calendars[{}].weeks[[{}]].today boolean Whether the Date is today's date.
calendars[{}].weeks[[{}]].prevMonth boolean Whether the Date is in the previous month. Useful when the showOutsideDays flag is used.
calendars[{}].weeks[[{}]].nextMonth boolean Whether the Date is in the next month. Useful when the showOutsideDays flag is used.

Inspiration and Thanks!

Other Solutions

Here are some other great daypicker solutions:

Contributors

Thanks goes to these people (emoji key):


Morgan Kartchner
💻 📖 💡 🤔 👀 ⚠️
Jen Luker
💻 💡 🤔
Sam Gale
💻 🤔
Arthur Denner
💻 🤔
Dony Sukardi
💻 💡 ⚠️
Amit Solanki
📖
Nathanael CHERRIER
💻 🤔 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT