kalendaryo

by geeofree

geeofree / kalendaryo

An unopinionated React date component :atom_symbol: + :date:fns

430 Stars 22 Forks Last release: about 2 years ago (v1.11.1) MIT License 72 Commits 18 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Kalendaryo

Coverage Status Build Status npm npm license

Build flexible react date components using primitives :atom_symbol: + :date:fns

Problem

You want a date component that's:
:heavycheckmark: Laid out the way you want
:heavycheckmark: Functions the way you want
:heavycheckmark: Flexible for your use case

This solution

Kalendaryo is an unopinionated React component for building calendars. It has no opinions about what your calendar component should look or function like but rather only helps you deal with those unique constraints by providing various variables your calendar component needs such as the calendar's state data and methods for getting(i.e. all the days in a month) and setting(i.e. selecting the date from a day) plus many more!

See the Basic Usage section to see how you can build a basic calendar component with Kalendaryo, or see the Examples section to see more examples built with Kalendaryo.


Table of Contents

Installation

This package expects you to have

>= [email protected]

npm i -d kalendaryo // 

Basic Usage

// Step 1: Import the component
import Kalendaryo from 'kalendaryo'

// Step 2: Invoke and pass your desired calendar as a function in the render prop const BasicCalendar = () =>

// Step 3: Build your calendar! function MyCalendar(kalendaryo) { const { getFormattedDate, getWeeksInMonth, getDayLabelsInWeek, setDatePrevMonth, setDateNextMonth, setSelectedDate } = kalendaryo

const currentDate = getFormattedDate("MMMM YYYY") const weeksInCurrentMonth = getWeeksInMonth() const dayLabels = getDayLabelsInWeek() const selectDay = date => () => setSelectedDate(date)

/* For this basic example we're going to build a calendar that has:

    1. A header where you have:
  • 1.1 Controls for moving to the previous/next month of the current date

  • 1.2 A label for current month & year of the current date

    1. A body where you have:
  • 2.1 A row for the label of the days of a week

  • 2.2 Rows containing the days of each week in the current date's month where you can:

  • 2.2.1 Select a date by clicking on a day

  • / return (

    // (1)
    // (1.1) ←
    // (1.2)
    <span classname="text-white">{currentDate}</span>
    
    // (1.1)
    <button onclick="{setDateNextMonth}">→</button>

    // (2)

    // (2.1)
    {dayLabels.map(label => (
    {label}
    ))}
    // (2.2)
    {weeksInCurrentMonth.map((week, i) =&gt; (
      <div classname="week" key="{i}">
        {week.map(day =&gt; (
          <div key="{day.label}" onclick="{selectDay(day.dateValue)}">
            {day.label}
          </div>
        ))}
      </div>
    ))}
    ) }

See this basic usage snippet in action here!

API

This section contains descriptions of the various things the

 component has to offer which are split into three parts:

  • state
    : Description of the component's state that could change
  • props
    : Description of the component's props that you can change or hook into
  • methods
    : Description of the component's various helper methods you can use from the render prop

State

#date

type: Date
default: new Date()

Is the state for the current date the component is in. By convention, this should only change when the calendar changes its current date, i.e. moving to and from a month or year on the calendar.

#selectedDate

type: Date
default: new Date()

Is the state for the selected date on the component. By convention, this should only change when the calendar receives a date selection input from the user, i.e. selecting a day on the calendar.

Props

#startCurrentDateAt

type: Date
required: false
default: new Date()

Modifies the initial value of

#date
. Great for when you want your calendar to boot up in some date other than today.

Note: Passing non-

Date
types to this prop sets the
#date
state to today.
const birthday = new Date(1995, 4, 27)


#startSelectedDateAt

type: Date
required: false
default: new Date()

Modifies the initial value of

#selectedDate
. Great for when you want your calendar's selected date to boot up in another date than today.

Note: Passing non-

Date
types to this prop sets the
#selectedDate
state to today.
const birthday = new Date(1988, 4, 27)


#defaultFormat

type: String
required: false
default: 'MM/DD/YY'

Modifies the default format value on the

#getFormattedDate
method. Accepts any format that date-fns'
format
function
can support.

const myFormat = 'yyyy-mm-dd'


#startWeekAt

type: Number[0..6]
required: false
default: 0

Modifies the starting day index of the weeks returned from

#getWeeksInMonth
&
#getDayLabelsInWeek
. Defaults to

0 (sunday)
const monday = 1


#onChange

type: func(state: Object): void
required: false

Callback prop for listening to state changes on the

#date
&
#selectedDate
states.

const logState = (state) => console.log(state)



#onDateChange

type: func(date: Date): void
required: false

Callback prop for listening to state changes only to the

#date
state.

const logDateState = (date) => console.log(date)


#onSelectedChange

type: func(date: Date): void
required: false

Callback prop for listening to state changes only to the

#selectedDate
state.

const logSelectedDateState = (selectedDate) => console.log(selectedDate)


#render

type: func(props: Object): void
required: true

Callback prop responsible for rendering the date component. This function receives an object which has the

state
,
methods
, as well as props you pass that are invalid(see passing variables to the render prop for more information).

const MyCalendar = (kalendaryo) => {
  console.log(kalendaryo)
  return 

Some layout

}


Passing variables to the render prop

Sometimes you may need to have states other than the

#date
and
#selectedDate
state, i.e for a date range calendar component, you may need to have a state for its

startDate
and
endDate
and may need to create the calendar component as a method inside the date range calendar's class like so:
class DateRangeCalendar extends React.Component {
  state = {
    startDate: null,
    endDate: null
  }

Calendar = (props) => { const { startDate, endDate } = this.state return // Your calendar layout }

setDateRange = (selectedDate) => { // Logic for updating the start and end date states }

render() { return } }

This however, leaves the

Calendar
component tightly coupled to the
DateRangeCalendar
component and makes it a little bit harder for us to keep track of what's going on with what.

If only we could separate the

DateRangeCalendar
's state logic and
Calendar
's UI rendering

To solve this, the

Kalendaryo
component can receive unknown props. These are props that gets passed to the
render
prop callback when it does not convey any meaning to the
Kalendaryo
component.

With unknown props we can pass any arbitrary variable to

Kalendaryo
as long as it does not know what to do with it i.e. the
startDate
and
endDate
states. We would then have no need to put the
Calendar
function inside of the
DateRangeCalendar
class since the states are now an injected dependency to the
Calendar
e.g
class DateRangeCalendar extends React.Component {
  state = {
    startDate: null,
    endDate: null
  }

setDateRange = (selectedDate) => { // Logic for updating the start and end date states }

render() { return ( ) } }

function Calendar(props) { const { startDate, endDate } = props return // Your calendar component }

With this, the

Calendar
and
DateRangeCalendar
are now separated to the things they're solely responsible for.

Methods

#getFormattedDate

type: func(date?: Date | format?: String, format?: String): String
throws: Error exception when the types of the given argument are invalid

Returns the date formatted by the given format string. You can invoke this in four ways: *

getFormattedDate()
- Returns the
#date
state formatted as the value set on the
#defaultFormat
prop
  • getFormattedDate(date)
    - Returns the given date argument formatted as the value set on the
    #defaultFormat
    prop
  • getFormattedDate(format)
    - Returns the
    #date
    state formatted to the given format string argument
  • getFormattedDate(date, format)
    - Returns the given date argument formatted to the given format string argument
function MyCalendar(kalendaryo) {
  const birthday = new Date(1988, 4, 27)
  const myFormattedDate = kalendaryo.getFormattedDate(birthday, 'yyyy-mm-dd')

return

My birthday is at {myFormattedDate}

}


#getDateNextMonth

type: func(date?: Date | amount?: Number, amount?: Number): Date
throws: Error exception when the types of the given argument are invalid

Returns a date with months added from the given amount. You can invoke this in four ways: *

getDateNextMonth()
- Returns the
#date
state with 1 month added to it
  • getDateNextMonth(date)
    - Returns the given date argument with 1 month added to it
  • getDateNextMonth(amount)
    - Returns the
    #date
    state with the months added to it from the given amount argument
  • getDateNextMonth(date, amount)
    - Returns the given date argument with the months added to it from the given amount argument
function MyCalendar(kalendaryo) {
  const nextMonth = kalendaryo.getDateNextMonth()
  const nextMonthFormatted = kalendaryo.getFormattedDate(nextMonth, 'MMMM')

return

The next month from today is: {nextMonthFormatted}

}


#getDatePrevMonth

type: func(date?: Date | amount?: Number, amount?: Number): Date
throws: Error exception when the types of the given argument are invalid

Returns a date with months subtracted from the given amount. You can invoke this in four ways: *

getDatePrevMonth()
- Returns the
#date
state with 1 month subtracted to it
  • getDatePrevMonth(date)
    - Returns the given date argument with 1 month subtracted to it
  • getDatePrevMonth(amount)
    - Returns the
    #date
    state with the months subtracted to it from the given amount argument
  • getDatePrevMonth(date, amount)
    - Returns the given date argument with the months subtracted to it from the given amount argument
function MyCalendar(kalendaryo) {
  const prevMonth = kalendaryo.getDatePrevMonth()
  const prevMonthFormatted = kalendaryo.getFormattedDate(prevMonth, 'MMMM')

return

The previous month from today is: {prevMonthFormatted}

}


#getDaysInMonth

type: func(date?: Date): DayObject[]
throws: Error exception when the types of the given argument are invalid

Returns an array of Day Objects for the month of a given date

  • getDaysInMonth()
    - Returns all the days in the month of the
    #date
    state
  • getDaysInMonth(date)
    - Returns all the days in the month of the given date argument
function MyCalendar(kalendaryo) {
  const nextMonth = kalendaryo.getDateNextMonth()
  const daysNextMonth = kalendaryo.getDaysInMonth(nextMonth)

return (

{daysNextMonth.map((day) => (

console.log(day.dateValue)} > {day.label}

))}
) }


#getWeeksInMonth

type: func(date?: Date, startingDayIndex?: Number): Week[DayObject[]]
throws: Error exception when the types of the given argument are invalid

Returns an array of weeks, each containing their respective days for the month of the given date

  • getWeeksInMonth()
    - Returns an array of weeks for the month of the
    #date
    state, with the weeks starting at the value specified from the
    #startWeekAt
    prop
  • getWeeksInMonth(date)
    - Returns an array of weeks for the month of the given date argument, with the weeks starting at the value specified from the
    #startWeekAt
    prop
  • getWeeksInMonth(date, startingDayIndex)
    - Returns an array of weeks for the month of the given date argument, with the weeks starting at the value specified from the given startingDayIndex argument
function MyCalendar(kalendaryo) {
  const prevMonth = kalendaryo.getDatePrevMonth()
  const weeksPrevMonth = kalendaryo.getWeeksInMonth(prevMonth, 1)

return (

{weeksPrevMonth.map((week, i) => (
{week.map((day) => (

console.log(day.dateValue)} > {day.label}

))}
))}
) }


#getDayLabelsInWeek

type: func(dayLabelFormat?: String): String[]

Returns an array of strings for each day on a week

  • getDayLabelsInWeek()
    - Returns an array of each day on a week formatted as
    'ddd'
    and starts on the week index based on the value set on the
    #startWeekAt
    prop
  • getDayLabelsInWeek(dayLabelFormat)
    - Returns an array of each day on a week formatted as the given dayLabelFormat argument and starts on the week index based on the value set on the
    #startWeekAt
    prop

#setDate

type: func(date: Date): void
throws: Error exception when the types of the given argument are invalid

Updates the

#date
state to the given date

function MyCalendar(kalendaryo) {
  const birthday = new Date(1988, 4, 27)
  const currentDate = kalendaryo.getFormattedDate()
  const setDateToBday = () => kalendaryo.setDate(birthday)

return (

The date is: {currentDate}

Set date to my birthday
) }


#setSelectedDate

type: func(selectedDate: Date): void
throws: Error exception when the types of the given argument are invalid

Updates the

#selectedDate
state to the given selected date

function MyCalendar(kalendaryo) {
  const birthday = new Date(1988, 4, 27)
  const currentDate = kalendaryo.getFormattedDate()
  const selectedDate = kalendaryo.getFormattedDate(kalendaryo.selectedDate)
  const selectBdayDate = () => kalendaryo.setSelectedDate(birthday)

return (

The date is: {currentDate}

The selected date is: {selectedDate}

Set selected date to my birthday!
) }


#pickDate

type: func(date: Date): void
throws: Error exception when the types of the given argument are invalid

Updates both the

#date
&
#selectedDate
state to the given date

function MyCalendar(kalendaryo) {
  const birthday = new Date(1988, 4, 27)
  const currentDate = kalendaryo.getFormattedDate()
  const selectedDate = kalendaryo.getFormattedDate(kalendaryo.selectedDate)
  const selectBday = () => kalendaryo.pickDate(birthday)

return (

The date is: {currentDate}

The selected date is: {selectedDate}

Set date and selected date to my birthday!
) }


#setDateNextMonth

type: func(): void

Updates the

#date
state by adding 1 month

function MyCalendar(kalendaryo) {
  const formattedDate = kalendaryo.getFormattedDate()
  return (
    

The date today is {formattedDate}

Click to set date to the next month
) }


#setDatePrevMonth

type: func(): void

Updates the

#date
state by subtracting 1 month

function MyCalendar(kalendaryo) {
  const formattedDate = kalendaryo.getFormattedDate()
  return (
    

The date today is {formattedDate}

Click to set date to the previous month
) }

Examples

Inspiration

This project is heavily inspired from Downshift by Kent C. Dodds, a component library that uses render props to expose certain APIs for you to build flexible and accessible autocomplete, dropdown, combobox, etc. components.

Without it, I would not have been able to create this very first OSS project of mine, so thanks Mr. Dodds and Contributors for it! :heart:

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.