doc: add more detail for calendar

Author: jason89521

doc-site/docs/react-use-calendar-component/index.mdx

@@ -6,6 +6,10 @@ title: Use Calendar
 
 This package is aimed to provide an easy-to-use API interface for those people who want to build their own calendar component with custom style.
 
+## Caveat
+
+This package is still under development, the API interface may change frequently.
+
 ## Install
 
 ```sh
@@ -52,80 +56,3 @@ const Calendar = () => {
   );
 };
 ```
-
-## API Reference
-
-```ts
-const {
-  selectedDates,
-  displayedYear,
-  displayedMonth,
-  changeDisplayedYear,
-  changeDisplayedMonth,
-  getDateCellInfos,
-} = useCalendarComponent({ initialDisplayedDate, selectType, value, onChange });
-```
-
-### Args
-
-#### `initialDisplayedDate`
-
-This value will be used to generate the date cells at beginning. Its default value is `new Date()`.
-
-#### `selectType`
-
-The selection type of the calendar, currently support `'single' | 'multiple'`. Its default value is `'single'`.
-
-> This option must be set if you don't want to use `single` type.
-
-#### `value`
-
-Set it up to get the full control of the calendar. For `'single'` selection type, the type of this value should be `Date`. For `'multiple'` selection type, the type of this value should be `Date[]`.
-
-#### `onChange`
-
-```ts
-type OnChange: (value: Date|Date[]) => void
-```
-
-For `single` selection type, the `value` is a `Date` instance. For `multiple` selection type, the `value` is an array of `Date` instances.
-
-### Returns
-
-#### `selectedDates`
-
-An array contains the `Date` instances of all selected date.
-
-#### `displayedYear`
-
-The year of the calendar which should be rendered.
-
-#### `displayedMonth`
-
-The month of the calendar which should be rendered.
-
-#### `changeDisplayedYear`
-
-Call this function to add a value to `displayedYear`.
-
-#### `changeDisplayedMonth`
-
-Call this function to add a value to `displayedMonth`.
-
-#### `getDateCellInfos`
-
-```ts
-interface DateCellInfo {
-  key: string;
-  year: number;
-  month: number;
-  dayOfMonth: number;
-  dayOfWeek: number;
-  isToday: boolean;
-  isSelected: boolean;
-  monthStatus: 'current' | 'next' | 'previous';
-  selectThisDate: (options?: SelectDateOptions) => void;
-}
-```
-
-This function returns an array of `DateCellInfo`. It can be used to render your calendar.

doc-site/docs/react-use-calendar-component/options.mdx

@@ -0,0 +1,61 @@
+---
+title: Options
+---
+
+```ts
+export type SelectType = 'single' | 'multiple';
+
+export type Value<S extends SelectType> = S extends 'single'
+  ? Date
+  : S extends 'multiple'
+  ? Date[]
+  : never;
+
+export type ExcludedDates = {
+  min?: Date;
+  max?: Date;
+  arbitrary?: Date[];
+};
+
+export type UseCalendarOptions<S extends SelectType = 'single'> = {
+  initialDisplayedDate?: Date;
+  selectType?: S;
+  value?: Value<S>;
+  onChange?: (value: Value<S>) => void;
+  excludedDates?: ExcludedDates;
+};
+
+// useCalendarComponent(your_options)
+```
+
+## `initialDisplayedDate`
+
+This value is used for displaying the current year and month. Default value is `new Date()`.
+
+## `selectTyps`
+
+The selecting type of the calendar component. These option will change the accepted `value` and the argument of `onChange`. Default value is `'single'`.
+
+## `value`
+
+For single mode, this option should be an instance of `Date`. For multiple mode, this options should be an array of `Date` instance. It can be useful when you want your calendar component be a controlled component.
+
+## `onChange`
+
+This function will be called when a date is selected by the `selectedThisDate` function which is generated for every date cell.
+
+## `excludedDates`
+
+If the date cell satisify the condition specified by this options, then the `isExcluded` flag will be set to `true`.
+
+### `min`
+
+Every date smaller than this value will be excluded.
+
+### `max`
+
+Every date larger than or equal to this value will be excluded.
+
+### `arbitrary`
+
+The date specified in this array will be excluded.

doc-site/docs/react-use-calendar-component/return.mdx

@@ -0,0 +1,56 @@
+---
+title: Return value
+---
+
+```ts
+export interface DateInfo {
+  year: number;
+  month: number;
+  monthDay: number;
+  weekDay: number;
+  isToday: boolean;
+  monthStatus: 'current' | 'next' | 'previous';
+}
+
+export interface DateCellInfo extends DateInfo {
+  key: string;
+  isSelected: boolean;
+  isExcluded: boolean;
+  selectThisDate: (options?: SelectDateOptions) => void;
+}
+
+export type ChangeDisplayedValue = (
+  value: number,
+  options?: { override?: boolean }
+) => void;
+
+interface Return {
+  displayedYear: number;
+  displayedMonth: number;
+  changeDisplayedYear: ChangeDisplayedValue;
+  changeDisplayedMonth: ChangeDisplayedValue;
+  getDateCellInfos: (year?: number, month?: number) => DateCellInfo[];
+}
+```
+
+## `displayedYear`
+
+The current year which should be displayed.
+
+## `displayedMonth`
+
+The current month which should be displayed.
+
+## `changeDisplayedYear`
+
+Add `displayedYear` by a value. For example, if `displayedYear` is `2022`, then `changeDisplayedYear(1)` will change `displayedYear` to `2023`.
+
+If `options.override` is set to `true`, then `displayedYear` will be set to `1`.
+
+## `changeDisplayedMonth`
+
+Like `changeDisplayYear`, but change `displayedMonth` instead.
+
+## `getDateCellInfos`
+
+Use this function to get the calendar of the specified `year` and `month`. The default value of `year` and `month` is `displayedYear` and `displayedMonth`.

packages/react-use-calendar-component/README.md

@@ -15,93 +15,3 @@ This package is still under development, the API interface may change frequently
 - [ ] Support disabled date
 - [ ] Support displaying two calendar
 - [ ] Support week, month, year selection
-
-## Examples
-
-- [Single Mode](./src/app/components/Examples/Single.tsx)
-- [Multiple Mode](./src/app/components/Examples/Multiple.tsx)
-
-## Install
-
-```sh
-npm install react-use-calendar-component
-```
-
-## API Reference
-
-```ts
-import useCalendarComponent from 'react-use-calendar-component';
-
-const {
-  selectedDates,
-  displayedYear,
-  displayedMonth,
-  changeDisplayedYear,
-  changeDisplayedMonth,
-  getDateCellInfos,
-} = useCalendarComponent({ initialDisplayedDate, selectType, value, onChange });
-```
-
-### Args
-
-#### `initialDisplayedDate`
-
-This value will be used to generate the date cells at beginning. Its default value is `new Date()`.
-
-#### `selectType`
-
-The selection type of the calendar, currently support `'single' | 'multiple'`. Its default value is `'single'`.
-
-> This option must be set if you don't want to use `single` type.
-
-#### `value`
-
-Set it up to get the full control of the calendar. For `'single'` selection type, the type of this value should be `Date`. For `'multiple'` selection type, the type of this value should be `Date[]`.
-
-#### `onChange`
-
-```ts
-type OnChange: (value: Date|Date[]) => void
-```
-
-For `single` selection type, the `value` is a `Date` instance. For `multiple` selection type, the `value` is an array of `Date` instances.
-
-### Returns
-
-#### `selectedDates`
-
-An array contains the `Date` instances of all selected date.
-
-#### `displayedYear`
-
-The year of the calendar which should be rendered.
-
-#### `displayedMonth`
-
-The month of the calendar which should be rendered.
-
-#### `changeDisplayedYear`
-
-Call this function to add a value to `displayedYear`.
-
-#### `changeDisplayedMonth`
-
-Call this function to add a value to `displayedMonth`.
-
-#### `getDateCellInfos`
-
-```ts
-interface DateCellInfo {
-  key: string;
-  year: number;
-  month: number;
-  dayOfMonth: number;
-  dayOfWeek: number;
-  isToday: boolean;
-  isSelected: boolean;
-  monthStatus: 'current' | 'next' | 'previous';
-  selectThisDate: (options?: SelectDateOptions) => void;
-}
-```
-
-This function returns an array of `DateCellInfo`. It can be used to render your calendar.