Month

A class which encapsulates a calendar view of a month, and offers information about the weeks and days within that calendar view.

  // December 2018 using Monday as week start
  const m = new Month({
      date         : '2018-12-01',
      weekStartDay : 1
  });

  m.eachWeek((week, dates) => console.log(dates.map(d => d.getDate())))

Configs

date: Date | String

The date which the month should encapsulate. May be a Date object, or a YYYY-MM-DD format string.

Mutating a passed Date after initializing a Month object has no effect on the Month object.

hideNonWorkingDays: Boolean

Configure as true to have the visibleDayColumnIndex and visibleColumnCount properties respect the configured nonWorkingDays.

nonWorkingDays: Object<String, Boolean>

Non-working days as an object where keys are day indices, 0-6 (Sunday-Saturday), and the value is true. Defaults to nonWorkingDays.

sixWeeks: BooleanAlso a property

Configure as true to always have the month encapsulate six weeks. This is useful for UIs which must be a fixed height.

weekStartDay: Number

The week start day, 0 meaning Sunday, 6 meaning Saturday. Defaults to weekStartDay.

Properties

canonicalDayNumbers: Number[]readonly

For use when this Month's weekStartDay is non-zero.

An array to map the days of the week 0-6 of this Calendar to the canonical day numbers used by the Javascript Date object.

dayColumnIndex: Number[]readonly

An array to map a canonical day number to a 0-6 column index. For example, if we have weekStartDay as Monday which is 1, then the calendar would look like

┌────┬────┬────┬────┬────┬────┬────┐
| Mo | Tu | We | Th | Fr | Sa | Su |
└────┴────┴────┴────┴────┴────┴────┘

So we'd need this array: [ 6, 0, 1, 2, 3, 4, 5]

dayCount: Numberreadonly

The number of days in the calendar for this month. This will always be a multiple of 7, because this represents the number of calendar cells occupied by this month.

endDate: Datereadonly

The date of the last cell in the calendar view of this month.

firstDate: Datereadonly

The first date of the current month.

lastDate: Datereadonly

The last date of the current month.

sixWeeks: BooleanAlso a config

Configure as true to always have the month encapsulate six weeks. This is useful for UIs which must be a fixed height.

startDate: Datereadonly

The date of the first cell in the calendar view of this month.

visibleDayColumnIndex: Number[]readonly

An array to map a canonical day number to a visible column index. For example, if we have weekStartDay as Monday which is 1, and non working days as Wednesday, and hideNonWorkingDays : true, then the calendar would look like

┌────┬────┬────┬────┬────┬────┐
| Mo | Tu | Th | Fr | Sa | Su |
└────┴────┴────┴────┴────┴────┘

So we'd need this array: [ 5, 0, 1, undefined, 2, 3, 4]

weekCount: Numberreadonly

The number of weeks in the calendar for this month.

weekLength: Numberreadonly

The number of visible days in the week as defined by the nonWorkingDays and hideNonWorkingDays options.

Functions

eachDay

Iterates through all calendar cells in this month, calling the passed function for each date.

Parameter	Type	Description
`fn`	function	The function to call.
`fn.date`	Date	The date for the cell.

eachWeek

Iterates through all weeks in this month, calling the passed function for each week.

Parameter	Type	Description
`fn`	function	The function to call.
`fn.week`	Number[]	An array containing `[year, weekNumber]`
`fn.dates`	Date[]	The dates for the week.

getWeekNumber

Returns the week of the year for the passed date. This returns an array containing two values, the year and the week number are returned.

The week number is calculated according to ISO rules, meaning that if the first week of the year contains less than four days, it is considered to be the last week of the preceding year.

The configured weekStartDay is honoured in this calculation. So if the weekStartDay is NOT the ISO standard of 1, (Monday), then the weeks do not coincide with ISO weeks.

Parameter	Type	Description
`date`	Date	The date to calculate the week for.

Returns: Number[] -

A numeric array: [year, week]

getWeekStart

Returns the week start date, based on the configured weekStartDay of the passed week.

Parameter Type Description

Parameter	Type	Description
`week`	Number \| Number[]	The week number in the current year, or an array containing `[year, weekOfYear]` for any year. Week numbers greater than the number of weeks in the year just wrap into the following year.

week

Number | Number[]

The week number in the current year, or an array containing [year, weekOfYear] for any year.

Week numbers greater than the number of weeks in the year just wrap into the following year.

Events

dateChange

Fired when setting the date property causes the encapsulated date to change in any way, date, week, month or year.

// Adding a listener using the "on" method
month.on('dateChange', ({ source, newDate, oldDate, changes, changes.d, changes.w, changes.m, changes.y, changes.r }) => {

});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.

monthChange

Fired when setting the date property causes a change of month. This will fire when changing to the same month in a different year.

// Adding a listener using the "on" method
month.on('monthChange', ({ source, newDate, oldDate, changes, changes.d, changes.w, changes.m, changes.y, changes.r }) => {

});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.

weekChange

Fired when setting the date property causes a change of week. Note that weeks are calculated in the ISO standard form such that if there are fewer than four days in the first week of a year, then that week is owned by the previous year.

The weekStartDay is honoured when making this calculation and this is a locale-specific value which defaults to the ISO standard of 1 (Monday) in provided European locales and 0 (Sunday) in the provided US English locale.

// Adding a listener using the "on" method
month.on('weekChange', ({ source, newDate, oldDate, changes, changes.d, changes.w, changes.m, changes.y, changes.r }) => {

});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.

yearChange

Fired when setting the date property causes a change of year.

// Adding a listener using the "on" method
month.on('yearChange', ({ source, newDate, oldDate, changes, changes.d, changes.w, changes.m, changes.y, changes.r }) => {

});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.

Event handlers

onDateChange

Called when setting the date property causes the encapsulated date to change in any way, date, week, month or year.

new Month({
    onDateChange({ source, newDate, oldDate, changes }) {

    }
});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.

onMonthChange

Called when setting the date property causes a change of month. This will fire when changing to the same month in a different year.

new Month({
    onMonthChange({ source, newDate, oldDate, changes }) {

    }
});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.

onWeekChange

Called when setting the date property causes a change of week. Note that weeks are calculated in the ISO standard form such that if there are fewer than four days in the first week of a year, then that week is owned by the previous year.

new Month({
    onWeekChange({ source, newDate, oldDate, changes }) {

    }
});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.

onYearChange

Called when setting the date property causes a change of year.

new Month({
    onYearChange({ source, newDate, oldDate, changes }) {

    }
});

Parameter	Type	Description
`source`	Month	The Month which triggered the event.
`newDate`	Date	The new encapsulated date value.
`oldDate`	Date	The previous encapsulated date value.
`changes`	Object	An object which contains properties which indicate what part of the date changed.
`changes.d`	Boolean	True if the date changed in any way.
`changes.w`	Boolean	True if the week changed (including same week in a different year).
`changes.m`	Boolean	True if the month changed (including same month in a different year).
`changes.y`	Boolean	True if the year changed.
`changes.r`	Boolean	True if the row count (with respect to the sixWeeks setting) changed.