Merge pull request '[update] calendar object and unsetWorkTime() api pages' (#112) from update-calendar-object-api-2110 into master

Reviewed-on: https://git.webix.io/Servers/gantt-docs/pulls/112
Reviewed-by: alex <[email protected]>

Author: alex

data/api/gantt_calendar_other.md

@@ -30,50 +30,92 @@ The **calendar** object possesses the following methods and properties:
                 - **_to_** - (*Date*) - the date when the time span is scheduled to be completed
                 - **_hours?_** - (*string[] | number[]*) - optional, an array of working hours as 'from'-'to' pairs.'false' value sets a day-off, 'true' (default value) applies the default hours (["8:00-17:00"])
                 - **_days?_** - (*WorkDaysTuple | boolean*) - optional, an array of 7 days of the week (from 0 - Sunday, to 6 - Saturday), where 1/true stands for a working day and 0/false - a non-working day.
-
 
 ~~~js
 calendar.setWorkTime({ hours:["9:00-18:00"] });
+calendar.setWorkTime({ day: 5, hours: ["9:00-18:00"] });
+calendar.setWorkTime({ day: 5, hours: false });
+calendar.setWorkTime({ date: new Date(2025, 5, 6), hours: ["9:00-18:00"] });
+calendar.setWorkTime({ date: new Date(2025, 5, 6), hours: false });
+calendar.setWorkTime({ hours: false });
+calendar.setWorkTime({
+  customWeeks: {
+    winter: {
+      from: new Date(2025, 11, 1),
+      to: new Date(2026, 2, 1),
+      hours: ["8:00-13:00", "14:00-16:00"],
+      days: [1, 1, 1, 1, 1, 0, 0]
+    },
+    summer: {
+      from: new Date(2026, 5, 1),
+      to: new Date(2026, 7, 1),
+      hours: ["10:00-13:00", "14:00-16:00"],
+      days: [1, 1, 0, 1, 1, 0, 0]
+    }
+  }
+});
+calendar.setWorkTime({
+  customWeeks: {
+    winter: {
+      from: new Date(2025, 11, 1),
+      to: new Date(2026, 2, 1),
+      hours: ["8:00-13:00", "14:00-16:00"],
+      days: [1, ["8:00-13:00"], 1, 1, ["14:00-16:00"], 0, 0]
+    },
+    summer: {
+      from: new Date(2026, 5, 1),
+      to: new Date(2026, 7, 1),
+      hours: ["10:00-13:00", "14:00-16:00"],
+      days: false
+    }
+  }
+});
 ~~~
 
 - <span class=submethod>**unsetWorkTime (config): void**</span> - unsets a working time in the Gantt Chart
     - **_config_** - (*object*) - the [configuration object](api/gantt_unsetworktime.md#configurationobjectproperties) of a time span:
         - **_day?_** - (*string | number*) - optional, a number of a week day [0 (Sunday) - 6 (Saturday)]. Note, you can set only 1 day at once
         - **_date?_** - (*Date*) - optional, a specific date to set as a working day or day off
         - **_hours?_** - (*string[] | number[] | boolean*) - optional, an array of working hours as 'from'-'to' pairs.
-'false' value sets a day-off, 'true' (default value) applies the default hours (["8:00-17:00"])
+'false' value unsets working hours, 'true' (default value) applies the default hours (["8:00-17:00"])
 
 
 ~~~js
-calendar.unsetWorkTime({ hours:["9:00-18:00"] });
+calendar.unsetWorkTime({ hours: ["9:00-18:00"] });
+calendar.unsetWorkTime({ day: "5", hours: ["9:00-18:00"] });
+calendar.unsetWorkTime({ day: 5, hours: false });
+calendar.unsetWorkTime({ date: new Date(2025, 5, 6), hours: true });
 ~~~
 
 - <span class=submethod>**isWorkTime (config, time_unit): boolean**</span> - checks whether the specified date is working 
     - **_config_** - (*Date | object*) - either a date to check or the [configuration object](api/gantt_isworktime.md#configurationobjectproperties) of a time span:
         - **_date_** - (*Date*) - a date to check
         - **_unit?_** - (*string*) - optional, a time unit: "minute", "hour", "day", "week", "month", "year"
-        - **_task?_** - (*Task*) - optional, the object of the task the duration of which should be calculated
-    - **_time_unit?_** - (*string*) - optional, a time unit: "minute", "hour", "day", "week", "month", "year". Not needed at all when the first parameter is specified as an object<br><br>
+    - **_time_unit?_** - (*string*) - optional, a time unit: "minute", "hour", "day", "week", "month", "year". Not needed at all when the first parameter is specified as an object
 
 ~~~js
 var calendar = gantt.getTaskCalendar(task);
 if (calendar.isWorkTime({date: date})){
     alert("worktime of task" + task.text);
 }
+
+calendar.isWorkTime(new Date(2025, 5, 6));
+calendar.isWorkTime(new Date(2025, 5, 6), "hour");
+calendar.isWorkTime({ date: new Date(2025, 5, 6), unit: "hour" });
 ~~~
 
 - <span class=submethod>**getClosestWorkTime (config): Date**</span> - returns the closest working time
     - **_config_** - (*Date | object*) - the [configuration object](api/gantt_getclosestworktime.md#configurationobjectproperties):
         - **_date_** - (*Date*) - a date to get the closest working time for
         - **_dir?_** - (*string*) - optional, specifies the direction of the closest time: "future" or "past" 
         - **_unit?_** - (*string*) - optional, a time unit to search for the closest working time
-        - **_task?_** - (*Task*) - optional, the object of the task to use its calendar
 
 ~~~js
-calendar.getClosestWorkTime({
-    date:new Date(2013,0,1), 
-    dir:"future", 
-    unit:"hour"
+calendar.getClosestWorkTime(new Date(2025, 5, 6));
+calendar.getClosestWorkTime({ 
+    date: new Date(2025, 5, 6), 
+    unit: "hour",
+    dir: "past" 
 });
 ~~~
 
@@ -83,26 +125,32 @@ calendar.getClosestWorkTime({
         - **_start_date_** - (*Date*) - the date when a task is scheduled to begin
         - **_duration_** - (*number*) - the duration of a task
         - **_unit?_** - (*string*) - optional, the time unit of the duration: "minute", "hour", "day", "week", "month", "year"
-        - **_task?_** - (*Task*) - optional, the object of the task the duration of which should be calculated
     - **_duration?_** - (*number*) - optional, the duration of a task. Not needed at all when the first parameter is specified as an object
     - **_unit?_** - (*string*) - optional, the time unit of the duration. Not needed at all when the first parameter is specified as an object<br>
 
 ~~~js
-var end_date = calendar.calculateEndDate({start_date:date, duration:duration});
+calendar.calculateEndDate(new Date(2025, 5, 6), 2, "hour");
+calendar.calculateEndDate({ 
+    start_date: new Date(2025, 5, 6), 
+    duration: 2, 
+    unit: "hour" 
+});
 ~~~
 
 - <span class=submethod>**calculateDuration (config, end): number**</span> - calculates the duration of a task 
     - **_config_** - (*Date | object*) - either the date when a task is scheduled to begin or the [configuration object](api/gantt_calculateduration.md#configurationobjectproperties) of a time span:
         - **_start_date_** - (*Date*) - the date when a task is scheduled to begin
         - **_end_date_** - (*Date*) - the date when a task is scheduled to be completed
-        - **_task?_** - (*Task*) - optional, the object of the task the duration of which should be calculated
     - **_end?_**	- (*Date*) - the date when a task is scheduled to be completed. Not needed at all when the first parameter is specified as an object<br>
 
 ~~~js
-calendar.calculateDuration(new Date(2013,02,15), new Date(2013,02,25));
+calendar.calculateDuration(new Date(2025, 5, 6), new Date(2025, 5, 17));
+calendar.calculateDuration({ 
+    start_date: new Date(2025, 5, 6), 
+    end_date: new Date(2025, 5, 17) 
+});
 ~~~
 
-
 ###Properties
 
 - <span class=subproperty>**id**</span> - (*string | number*) - the id of a task's calendar 

data/api/gantt_unsetworktime.md

@@ -15,9 +15,9 @@ unsetWorkTime
 gantt.config.work_time = true;
 
 // changes the working time of working days from ["8:00-17:00"] to ["9:00-18:00"]
-gantt.setWorkTime({ hours:["9:00-18:00"] });
+gantt.setWorkTime({ hours: ["9:00-18:00"] });
 // unsets the working time
-gantt.unsetWorkTime({ hours:["9:00-18:00"] });
+gantt.unsetWorkTime({ hours: ["9:00-18:00"] });
 
 @template:	api_method
 @descr:
@@ -51,32 +51,36 @@ The configuration object can contain the following properties:
     <tr>
 		<td colspan=2 style="text-align:left !important; ">
 ~~~js
-//makes all Mondays day-offs
-gantt.unsetWorkTime({ day:1, hours:false }); 
+// unsets working hours for Mondays 
+gantt.unsetWorkTime({ day: 1, hours: false }); 
 ~~~
 		</td>
 	</tr>
 	<tr>
 		<td rowspan=2><b id="date">date</b></td>
-        <td> a specific date to set as a working day or day off</td>
+        <td> a specific date to set/unset working hours for</td>
     </tr>
     <tr>
 		<td colspan=2 style="text-align:left !important; ">
 ~~~js
-//makes a specific date a day-off
-gantt.unsetWorkTime({date:new Date(2013,0,1), hours:false})
+// unsets working hours for a specific date 
+gantt.unsetWorkTime({ 
+	date: new Date(2025, 11, 1), 
+	hours: false 
+});
 ~~~
 		</td>
 	</tr>
     <tr>
 		<td rowspan=2><b id="hours">hours</b></td>
-        <td> an array of working hours as 'from'-'to' pairs. <br><i>'false'</i> value sets a day-off, <i>'true' (default value)</i> applies the default hours (["8:00-17:00"])</td>
+        <td> an array of working hours as 'from'-'to' pairs. <br><i>'false'</i> value unsets working hours, 
+        <i>'true' (default value)</i> applies the default hours: (["8:00-17:00"])</td>
     </tr>
     <tr>
 		<td colspan=2 style="text-align:left !important; ">
 ~~~js
-//sets the working time for Fridays from 8:00 till 12:00
-gantt.unsetWorkTime({day : 5, hours : ["8:00-12:00"]});
+// unsets the working time for Fridays from 8:00 till 12:00
+gantt.unsetWorkTime({ day : 5, hours : ["8:00-12:00"] });
 ~~~
 		</td>
 	</tr>