Skip to content

Commit f144a89

Browse files
author
Dohyung Ahn
committed
docs: create JSDoc of CalendarCore and TZDate
1 parent cef12dc commit f144a89

File tree

5 files changed

+321
-30
lines changed

5 files changed

+321
-30
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ build/
4747
storybook-static/
4848
dist/
4949
apps/calendar/types/
50+
tmpdoc/
5051

5152
# etc
5253
*.swp

‎apps/calendar/src/factory/calendar.tsx

+9-2
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,23 @@ import { InvalidViewTypeError } from '@src/utils/error';
77

88
import type { Options, ViewType } from '@t/options';
99

10-
// @TODO: move this function to a separate file such as util
10+
// TODO: move this function to a separate file such as util
1111
function isValidViewType(viewType: string): viewType is ViewType {
1212
return !!Object.values(VIEW_TYPE).find((type) => type === viewType);
1313
}
1414

15+
/**
16+
* Calendar class
17+
*
18+
* @class Calendar
19+
* @extends CalendarCore
20+
* @param {object} options - Calendar options. Check out {@link CalendarCore} for more information.
21+
*/
1522
export default class Calendar extends CalendarCore {
1623
constructor(container: Element | string, options: Options = {}) {
1724
super(container, options);
1825

19-
const { defaultView = 'month' } = options;
26+
const { defaultView = 'week' } = options;
2027

2128
if (!isValidViewType(defaultView)) {
2229
throw new InvalidViewTypeError(defaultView);

‎apps/calendar/src/factory/calendarCore.tsx

+153-21
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,140 @@ import type {
3333
} from '@t/store';
3434
import type { ThemeState, ThemeStore } from '@t/theme';
3535

36+
/**
37+
* {@link https://nhn.github.io/tui.code-snippet/latest/CustomEvents CustomEvents} document at {@link https://github.com/nhn/tui.code-snippet tui-code-snippet}
38+
* @typedef {CustomEvents} CustomEvents
39+
*/
40+
41+
/**
42+
* Define Calendars to group events.
43+
*
44+
* @typedef {object} CalendarInfo
45+
* @property {string} id - Calendar id.
46+
* @property {string} name - Calendar name.
47+
* @property {string} color - Text color of events.
48+
* @property {string} borderColor - Left border color of events.
49+
* @property {string} backgroundColor - Background color of events.
50+
* @property {string} dragBackgroundColor - Background color of events during dragging.
51+
*/
52+
53+
/**
54+
* Timezone options of the calendar instance.
55+
*
56+
* For more information, see {@link TODO-GitHub-Options|Timezone options} in guide.
57+
*
58+
* @typedef {object} TimezoneOptions
59+
* @example
60+
* const calendar = new Calendar('#container', {
61+
* timezone: {
62+
* // @property {string} zones[].timezoneName - Timezone name. it should be one of IANA timezone names.
63+
* // @property {string} [zones[].displayLabel] - Display label of timezone.
64+
* // @property {string} [zones[].tooltip] - Tooltip of the element of the display label.
65+
* zones: [
66+
* {
67+
* timezoneName: 'Asia/Seoul',
68+
* displayLabel: 'UTC+9:00',
69+
* tooltip: 'Seoul'
70+
* },
71+
* {
72+
* timezoneName: 'Europe/London',
73+
* displayLabel: 'UTC+1:00',
74+
* tooltip: 'BST'
75+
* }
76+
* ],
77+
* // This function will be called for rendering components for each timezone.
78+
* // You don't have to use it if you're able to `Intl.DateTimeFormat` API with `timeZone` option.
79+
* // this function should return timezone offset from UTC.
80+
* // for instance, using moment-timezone:
81+
* customOffsetCalculator: (timezoneName, timestamp) => {
82+
* return moment.tz(timezoneName).utcOffset(timestamp);
83+
* }
84+
* }
85+
* });
86+
* @property {Array.<object>} zones - Timezone data.
87+
* @property {string} zones[].timezoneName - Timezone name. it should be one of IANA timezone names.
88+
* @property {string} [zones[].displayLabel] - Display label of timezone.
89+
* @property {string} [zones[].tooltip] - Tooltip of the element of the display label.
90+
* @property {function} customOffsetCalculator - Custom offset calculator when you're not able to leverage `Intl.DateTimeFormat` API.
91+
*/
92+
93+
/**
94+
* Object to create/modify events.
95+
* @typedef {object} EventObject
96+
* @property {string} [id] - Event id.
97+
* @property {string} [calendarId] - Calendar id.
98+
* @property {string} [title] - Event title.
99+
* @property {string} [body] - Body content of the event.
100+
* @property {string} [isAllday] - Whether the event is all day or not.
101+
* @property {string|number|Date|TZDate} [start] - Start time of the event.
102+
* @property {string|number|Date|TZDate} [end] - End time of the event.
103+
* @property {number} [goingDuration] - Travel time which is taken to go.
104+
* @property {number} [comingDuration] - Travel time which is taken to come back.
105+
* @property {string} [location] - Location of the event.
106+
* @property {Array.<string>} [attendees] - Attendees of the event.
107+
* @property {string} [category] - Category of the event. Available categories are 'milestone', 'task', 'time' and 'allday'.
108+
* @property {string} [dueDateClass] - Classification of work events. (before work, before lunch, before work)
109+
* @property {string} [recurrenceRule] - Recurrence rule of the event.
110+
* @property {string} [state] - State of the event. Available states are 'Busy', 'Free'.
111+
* @property {boolean} [isVisible] - Whether the event is visible or not.
112+
* @property {boolean} [isPending] - Whether the event is pending or not.
113+
* @property {boolean} [isFocused] - Whether the event is focused or not.
114+
* @property {boolean} [isReadOnly] - Whether the event is read only or not.
115+
* @property {boolean} [isPrivate] - Whether the event is private or not.
116+
* @property {string} [color] - Text color of the event.
117+
* @property {string} [backgroundColor] - Background color of the event.
118+
* @property {string} [dragBackgroundColor] - Background color of the event during dragging.
119+
* @property {string} [borderColor] - Left border color of the event.
120+
* @property {object} [customStyle] - Custom style of the event. the key of CSS property should be camelCase (e.g. {'fontSize': '12px'})
121+
* @property {*} [raw] - Raw data of the event. it's an arbitrary property for anything.
122+
*/
123+
124+
/**
125+
* CalendarCore class
126+
*
127+
* @class CalendarCore
128+
* @mixes CustomEvents
129+
* @param {string|Element} container - container element or selector.
130+
* @param {object} options - calendar options. For more information, see {@link TODO-GitHub-Options|Calendar options} in guide.
131+
* @param {string} [options.defaultView="week"] - Initial view type. Available values are: 'day', 'week', 'month'.
132+
* @param {boolean} [options.useFormPopup=false] - Whether to use the default form popup when creating/modifying events.
133+
* @param {boolean} [options.useDetailPopup=false] - Whether to use the default detail popup when clicking events.
134+
* @param {boolean} [options.isReadOnly=false] - Whether the calendar is read-only.
135+
* @param {boolean} [options.usageStatistics=true] - Whether to allow collect hostname and send the information to google analytics.
136+
* For more information, check out the {@link https://github.com/nhn/tui.calendar/tree/main/apps/calendar#collect-statistics-on-the-use-of-open-source|documentation}.
137+
* @param {function} [options.eventFilter] - A function that returns true if the event should be displayed. the default filter checks if the event's `isVisible` property is true.
138+
* @param {object} [options.week] - Week option of the calendar instance.
139+
* @param {number} [options.week.startDayOfWeek=0] - Start day of the week. Available values are 0 (Sunday) to 6 (Saturday).
140+
* @param {Array.<string>} [options.week.dayNames] - Names of days of the week. Should be 7 items starting from Sunday to Saturday. If not specified, the default names are used.
141+
* Default values are ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].
142+
* @param {boolean} [options.week.workweek=false] - Whether to exclude Saturday and Sunday.
143+
* @param {boolean} [options.week.showTimezoneCollapseButton=true] - Whether to show the timezone collapse button.
144+
* @param {boolean} [options.week.timezonesCollapsed=false] - Whether to collapse the timezones.
145+
* @param {number} [options.week.hourStart=0] - Start hour of the day. Available values are 0 to 24.
146+
* @param {number} [options.week.hourEnd=24] - End hour of the day. Available values are 0 to 24. Must be greater than `hourStart`.
147+
* @param {boolean} [options.week.narrowWeekend=false] - Whether to narrow down width of weekends to half.
148+
* @param {boolean|Array.<string>} [options.week.eventView=true] - Determine which view to display events. Available values are 'allday' and 'time'. set to `false` to disable event view.
149+
* @param {boolean|Array.<string>} [options.week.taskView=true] - Determine which view to display tasks. Available values are 'milestone' and 'task'. set to `false` to disable task view.
150+
* @param {object} options.month - Month option of the calendar instance.
151+
* @param {number} [options.month.startDayOfWeek=0] - Start day of the week. Available values are 0 (Sunday) to 6 (Saturday).
152+
* @param {Array.<string>} [options.month.dayNames] - Names of days of the week. Should be 7 items starting from Sunday to Saturday. If not specified, the default names are used.
153+
* Default values are ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'].
154+
* @param {boolean} [options.month.workweek=false] - Whether to exclude Saturday and Sunday.
155+
* @param {boolean} [options.month.narrowWeekend=false] - Whether to narrow down width of weekends to half.
156+
* @param {number} [options.month.visibleWeeksCount=0] - Number of weeks to display. 0 means display all weeks.
157+
* @param {Array.<CalendarInfo>} [options.calendars] - Calendars to group events.
158+
* @param {boolean|object} [options.gridSelection=true] - Whether to enable grid selection. or it's option. it's enabled when the value is `true` and object and will be disabled when `isReadOnly` is true.
159+
* @param {boolean} options.gridSelection.enableDbClick - Whether to enable double click to select area.
160+
* @param {boolean} options.gridSelection.enableClick - Whether to enable click to select area.
161+
* @param {TimezoneOptions} options.timezone - Timezone option of the calendar instance. For more information about timezone, check out the {@link TODO-GitHub-Options|Options} in guide.
162+
* @param {Theme} options.theme - Theme option of the calendar instance. For more information, see {@link TODO-GitHub-Theme|Theme} in guide.
163+
* @param {TemplateConfig} options.template - Template option of the calendar instance. For more information, see {@link TODO-GitHub-Template|Template} in guide.
164+
*/
36165
export default abstract class CalendarCore implements EventBus<ExternalEventTypes> {
37166
protected container: Element | null;
38167

39168
/**
40169
* start and end date of weekly, monthly
41-
* @type {object}
42170
* @private
43171
*/
44172
protected renderRange: {
@@ -241,7 +369,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
241369

242370
/**
243371
* Create events and render calendar.
244-
* @param {EventObject[]} events - list of {@link EventObject}
372+
* @param {Array.<EventObject>} events - list of {@link EventObject}
245373
* @example
246374
* calendar.createEvents([
247375
* {
@@ -283,7 +411,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
283411
*
284412
* @param {string} eventId - event's id
285413
* @param {string} calendarId - calendar's id of the event
286-
* @returns {EventObject | null} event. If the event can't be found, it returns null.
414+
* @returns {EventObject|null} event. If the event can't be found, it returns null.
287415
*
288416
* @example
289417
* const event = calendar.getEvent(eventId, calendarId);
@@ -339,7 +467,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
339467
/**
340468
* Set events' visibility by calendar ID
341469
*
342-
* @param {string|string[]} calendarId - The calendar id or ids to change visibility
470+
* @param {string|Array.<string>} calendarId - The calendar id or ids to change visibility
343471
* @param {boolean} isVisible - If set to true, show the events. If set to false, hide the events.
344472
*/
345473
setCalendarVisibility(calendarId: string | string[], isVisible: boolean) {
@@ -400,7 +528,6 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
400528
}
401529

402530
/**
403-
* TODO: implement this
404531
* Scroll to current time on today in case of daily, weekly view.
405532
*
406533
* @example
@@ -461,7 +588,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
461588
/**
462589
* Move to specific date.
463590
*
464-
* @param {DateType} date - The date to move
591+
* @param {Date|string|number|TZDate} date - The date to move. it should be eligible parameter to create a `Date` instance if `date` is string or number.
465592
* @example
466593
* calendar.on('clickDayName', (event) => {
467594
* if (calendar.getViewName() === 'week') {
@@ -516,7 +643,11 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
516643
* Change color values of events belong to a certain calendar.
517644
*
518645
* @param {string} calendarId - The calendar ID
519-
* @param {CalendarColor} colorOptions - The {@link CalendarColor} object
646+
* @param {object} colorOptions - The color values of the calendar
647+
* @param {string} colorOptions.color - The text color of the events
648+
* @param {string} colorOptions.borderColor - Left border color of events
649+
* @param {string} colorOptions.backgroundColor - Background color of events
650+
* @param {string} colorOptions.dragBackgroundColor - Background color of events during dragging
520651
*
521652
* @example
522653
* calendar.setCalendarColor('1', {
@@ -547,7 +678,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
547678
/**
548679
* Change current view type.
549680
*
550-
* @param {ViewType} viewName - The new view name to change
681+
* @param {string} viewName - The new view name to change to. Available values are 'month', 'week', 'day'.
551682
*
552683
* @example
553684
* // change to daily view
@@ -592,7 +723,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
592723
/**
593724
* Set the theme of the calendar.
594725
*
595-
* @param {DeepPartial<ThemeState>} theme - theme object
726+
* @param {Theme} theme - The theme object to apply. For more information, see {@link TODO-GitHub-Theme|Theme} in guide.
596727
*
597728
* @example
598729
* calendar.setTheme({
@@ -620,9 +751,9 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
620751
}
621752

622753
/**
623-
* Get current {@link Options}.
754+
* Get current options.
624755
*
625-
* @returns {Options} options
756+
* @returns {Options} - The current options of the instance
626757
*/
627758
getOptions() {
628759
const { options, template } = this.getStoreState();
@@ -636,11 +767,13 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
636767
}
637768

638769
/**
639-
* Set options of calendar.
770+
* Set options of calendar. For more information, see {@link TODO-GitHub-Options|Options} in guide.
640771
*
641-
* @param {Options} options - set {@link Options}
772+
* @param {Options} options - The options to set
642773
*/
643-
setOptions({ theme, template, ...restOptions }: Options) {
774+
setOptions(options: Options) {
775+
// destructure options here for tui.doc to generate docs correctly
776+
const { theme, template, ...restOptions } = options;
644777
const { setTheme } = this.theme.getState().dispatch;
645778
const {
646779
options: { setOptions },
@@ -659,7 +792,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
659792
}
660793

661794
/**
662-
* Get current rendered date.
795+
* Get current rendered date. (see {@link TZDate} for further information)
663796
*
664797
* @returns {TZDate}
665798
*/
@@ -670,7 +803,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
670803
}
671804

672805
/**
673-
* Start time of rendered date range. ({@link TZDate} for further information)
806+
* Start time of rendered date range. (see {@link TZDate} for further information)
674807
*
675808
* @returns {TZDate}
676809
*/
@@ -679,7 +812,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
679812
}
680813

681814
/**
682-
* End time of rendered date range. ({@link TZDate} for further information)
815+
* End time of rendered date range. (see {@link TZDate} for further information)
683816
*
684817
* @returns {TZDate}
685818
*/
@@ -690,7 +823,7 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
690823
/**
691824
* Get current view name('day', 'week', 'month').
692825
*
693-
* @returns {ViewType} current view name
826+
* @returns {string} current view name ('day', 'week', 'month')
694827
*/
695828
getViewName(): ViewType {
696829
const { currentView } = this.getStoreState('view');
@@ -709,12 +842,11 @@ export default abstract class CalendarCore implements EventBus<ExternalEventType
709842
setCalendars(calendars);
710843
}
711844

845+
// TODO: specify position of popup
712846
/**
713-
* TODO: specify position of popup
714-
*
715847
* Open event form popup with predefined form values.
716848
*
717-
* @param {EventObject} event - The preset {@link EventObject} data
849+
* @param {EventObject} event - The predefined {@link EventObject} data to show in form.
718850
*/
719851
openFormPopup(event: EventObject) {
720852
const { showFormPopup } = this.getStoreDispatchers().popup;

0 commit comments

Comments
 (0)