calender-carousal-react-ts

The Calendar Carousel is a mobile-responsive element designed to highlight a chosen date and time. You may have encountered similar instances in booking web applications, where the selected dates are always kept visible to ensure a smooth user experience.

Table of contents

• Project Name
  • Table of contents
  • Installation
  • Usage
  • API
    • Components
      • CalendarProvider
      • CalendarCarousalContainer
    • Hooks
      • useCalendar
    • Custom Types
      • DateType
      • Formats
      • CardBreakPoint
      • UnavailableHrs
      • UnavailableDates
      • Selected
      • CalendarTheme
      • DateRange
      • CustomStyles
    • Utils
      • getDatesList
      • getMean
      • getFormattedDate
      • getUnavailableTime
      • formattedDuration
      • getFormattedTime
  • Built With
  • License

Installation

You can install calender-carousal-package-react-ts using npm.

npm i calender-carousal-package-react-ts

Usage

import { CalendarProvider } from 'calender-carousal-package-react-ts'
const App = () => {
  return (
    <CalendarProvider>
      {...}
    </CalendarProvider>
  )
}

export default App

import CalenderCarousalContainer from 'calender-carousal-package-react-ts'

const TestComponent = () => {
  return (
    {...}
      <CalenderCarousalContainer />
    {...}
  )
}

export default TestComponent

API

The CalenderCarousalContainer component can be used by wrapping it in the CalendarProvider, both imported from Calender-Carousel. All of the calendar’s state management and date logic are bundled in useCalendar custom hook.

Components 

CalendarProvider

Prop	Description	Type	Default
datesRange	The Range of dates displayed in the Carousel	DateType[]	1 Week From CurrentDay
intervalStep	The Time Span by which duration should increase or decrease	Duration	Value of span is 15 & Unit is "Min" You can choose any span value with avaiable units (Hrs,Mins & Days).
formats	The display format for date, time, and clock	Formats	Default Formats are Dates : "DD MM YYYY" Clock : "12h" Time : "hh:mm A"
minDuration	Lower threshold for the duration (in Minutes,Hours & Days)	Duration	Default value of span is 30 & Unit is "Mins"
maxDuration	Upper threshold for the duration (in Minutes,Hours & Days)	Duration	Default value of span is 180 & Unit is "Mins"
cardsBreakPoints	Numbers of cards per screen to be displayed in Carousal	CardBreakPoint	Default Values of Card Break Points
unavailableDates	You can Either give List of Unavailable Dates or a Callback which will specifies the dates that cannot be selected	UnavailableDate[] |(date: Dayjs) => boolean	Default value is Sunday
unavailableHours	Hours that should be closed in Time Picker	UnavailableHrs	12 AM TO 2 AM
theme	Theme for the calendar and the components within	CalendarTheme

CalendarCarousalContainer

Prop	Description	Type	Default
activePanels	What panels should initially be opened	string | string[]	['1']
dateComponent	Component that will replace the card carousel	ReactNode
timeComponent	Component that will replace the time picker	ReactNode
durationComponent	Component that will replace the duration setter	ReactNode

Hooks 

useCalendar

This custom hook provides access to all the state values of the package, along with the functions to update the state.

Name	Description	Type
selected	Selected date, time, and duration	Selected
setDate	Function to update the selected date	(date: Dayjs) => void
setTime	Function to update the selected time	(time: Dayjs) => void
handleIncrementClick	Function to increase the selected duration	(offsetValue: Duration) => number
handleDecrementClick	Function to decrease the selected duration	(offsetValue: Duration) => number
dateList	The dates displayed in the carousel	DateType[]
intervalStep	The Time Span by which duration should increase or decrease	Duration
formats	The display format for date, time, and clock	Formats
minDuration	Lower threshold for the duration (in Minutes,Hours & Days)	Duration
maxDuration	Upper threshold for the duration (in Minutes,Hours & Days)	Duration
cardsBreakPoints	Numbers of cards per screen to be displayed in Carousal	CardBreakPoint
unavailableDates	You can Either give List of Clode Dates or a Callback which will specifies the dates that cannot be selected	UnavailableDate[] |(date: Dayjs) => boolean
unavailableHours	Hours that should be closed in Time Picker	UnavailableHrs

Custom Types

DateType

Date entry with its associated information.

type DateType = {
  date: Dayjs
  unavailable?: boolean
}

Formats

Display format for the date, time and allow the selection of 12 or 24 hour format.

type Formats = {
  date: string 
  time: string 
  clock: '12h' | '24h' 
}

Duration

Duration format for defining time intervals.

type Duration = {
  span: number;
  unit: string;
};

CardBreakPoint

Number of cards to display per slide based on the different screen sizes.

export type CardBreakPoint = {
  xs: number 
  sm: number
  md: number
  xl: number
  xxl: number
}

UnavailableHrs

Range of unavailable hours, including start and end.

export type UnavailableHrs = {
  start: number;
  end: number;
};

UnavailableDate

Date that would be unavaible in Calendar

export type UnavailableDate, = {
  string|Dayjs
};

Selected

export type Selected = {
  date: Dayjs | null
  time: Dayjs | null
  Duration: number 
}

CalendarTheme

type CalendarTheme = {
  isDark: boolean /**@default false */
  general?: Partial<AliasToken>
  custom?: Partial<CustomStyles>
}

DateRange

export type DateRange= {
  start: Dayjs 
  end: Dayjs 
  
}

CustomStyles

custom styles allow for component-specific customization. Below are the styles that can be applied.

Name	Description	Type
colorCardHeader	Header color for open date cards	string
colorCardHeaderText	Text color for date card header	string
colorCardBodyText	Text color for date card body	string
colorButton	Color for the duration buttons	string
colorTimePicker	Color for the TimePicker component	string
cardGap	Gap between the date cards in the carousel	number
buttonBorderRadius	Border radius of buttons that update duration	number

Default Card Breakpoints Values

Default number of cards to display per slide based on the different screen sizes.

export const CARD_BREAKPOINT: CardBreakPoint = {
  xs: 1,
  sm: 2,
  md: 3,
  lg: 5,
  xl: 7,
  xxl: 9,
}

Utils

getDatesList

returns: DateType[]
Get a list of dates consisiting of the Range you provided as props.

Param	Description	Type
Range	Range of Date you want to Display	{DateRange}(#DateRange)
unavaiableDates	Dates that should be closed	string | Dayjs

getMeanDuration

returns: number
Get mean value for the Duration.

Param	Description	Type
minDuration	Minimum Value of Duration in min	Duration
maxDuration	Maximum Value of Duration in min	Duration

formattedDuration

returns: string
Convert minutes into hour representation.

Param	Description	Type
minutes	The duration in minutes	number

getFormattedTime

returns: string
Convert time to a formatted string.

Param	Description	Type
time	The time to format	Dayjs | null
format	The format to return	string

getUnavailableTime

returns: [number]
Get Unvailable hours

Param	Description	Type
{Unavailable Hours}	Hours that are unavailable	null

Built Using

• React + TypeScript using Vite
• Dayjs
• Ant Design

License

Copyright © 2023 Muhammad Talha.