Content
Updated by Parimal Satyal about 3 years ago
This sub-feature is part of the epic related to the duration feature (<mention class="mention" data-id="31992" data-type="work_package" data-text="#31992">#31992</mention>) and describes the functioning of the new date picker for 12.2, **without the duration and non-working day features.**
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31798/content"></div></figure>
### **Acceptance criteria**
Clicking on a date field displays the date picker drop modal:
#### Overview
The date picker consists of these sections (see [Anatomy](https://community.openproject.org/#anatomy) below for design anatomy), each of which is described in more detail below:
* **An information/warning banner**
* **Scheduling option selection**
* **Start date and finish date**
* **The two-month mini-calendar**
* **Action bar**
#### Default behaviour
When the date picker is opened, a field is always in focus by default.
* When opened by clicking the "start date" field, the start date will be in focus by default.
* When opened by clicking the "finish date" field, the finish date will be in focus by default.
_(For information, when the unified date field is implemented, clicking on it:_
* _Will open the date picker with the start date in focus.)_
When all fields are cleared, and a date/day is clicked:
* That date will be considered a start date by default.
* However, if the user then clicks on a second date prior to that initially selected date, that second date will now be considered the start date, and the initial one the finish date.
* _This behaviour needs to be tested in implementaiton to ensure it "feels" right, especially when making a series of modficcations._
#### Warning/Information Banner
We use this banner to inform or warn the user when there is information contextual information.
* There can be two types of banners:
* An **information banner** has a blue background and is purely informational, to give the user additional context they might otherwise miss
* A **warning banner** has an orange background and indicates that changes to this work package may have destructive or unintended consequences (affect the dates/scheduling of other work packages)
* It consists of:
* an icon
* two-line message, the first in bold
* a "GANTT preview" button that, when clicked, opens up a GANTT preview in a new window that allows the user to view relations affecting this work package.
* This is a filtered work package list (table view + GANTT view) showing only work packages related to the "main" work package (the one for which the GANTT preview was requested).
* _**Open:** We might have to show some kind of message to inform the user that certain work packages might be invisible (filtered out, or no permission)._
* There are five identified cases in which this banner is displayed:
* **Information:** The dates are automatically derived from relations (and date input is disabled in regular mode)
* **Warning:** Manual scheduling is enabled so all existing work package relations are ignored.
* ~~**Information:** Changing the dates of this work package will affect the total project duration~~.
* **Warning:** Changing the dates of this work package will change the dates of related work packages
* **Information:** Available start and finish dates are limited by relations.
#### Regular/Manual Scheduling
* There are two modes
* **Regular** is the default scheduling mode where relations and project constraints are taken into account.
* **Manual** ignores work package relations and project constraints and functions as it does today when "manual scheduling" is checked.
* A helper icon in the label will display a tooltip with this text on hover :
* "Regular scheduling takes relations and project constraints into consideration, manual will ignore them."
#### Start Date and Finish Date
* There are two fields that use the new text field components of equal width:
* Start date
* Finish date
* The user is able to input dates either:
* by clicking on the dates on the mini-calendar (in the date picker modal)
* by inputting the dates manually in the text fields for start date and finish date in ISO format.
* Selecting a start date by clicking on a date or by inputting and pressing tab will move the focus to the finish date.
* On focus, the field is outlined in blue (focus style).
* The focus on the field also determines what is selected when the user clicks on a day in the calendar (i.e, clicking on the the start date field and then clicking on a date sets that date to the start date).
* **\[open\]** The visual format for displaying dates depends on the locale settings.
* Or we will use the ISO format everywhere. (to be discussed)
* ~~When in focus, the date text field should convert the date into an ISO format ("2022-03-31"). The user can then manually modify the date or enter a new date in this format.~~
* ~~On blur (focus removed), the display goes back to a more readable format (depending on locale, eg. "Thu 31.03.2022")~~
#### The two-month mini-calendar
The mini calendar allows the user to select start and end dates:
* Two months are displayed (current and next month)
* Clicking on backwards/forwards advances the calendar by a single month (eg. clicking on "forward" displays displays on the first calendar the month that was previously in the second calendar).
* **\[open\]** Is the change applied on blur (focus out) or directly on input?
* Today, entering date will "select" it immediately. We might retain this behaviour.
* When the date fields are empty:
* Clicking on a date on the calendar will set it as the start date.
* Hovering on any date _**after**_ that initially selected date:
* will give a "preview" of the end date (as in, all dates between the selected start date and this second date will be highlighted on hover).
* Clicking on a date will then set that as the finish date.
* Hovering on any date _before_ that initially selected date:
* will also give a "preview" of the period selected, but in considering that first date as the finish date.
* Clicking on a date will then set that second date as start date, and the initially selected date as the finish date.
* The start and finish dates field have "clear" buttons on focus that allow the user to clear that date (current behaviour).
* **\[open\]** If, in our design system, we decide to always show the clear button (x) even on blur, these fields will respect that.
* The start and finish dates are have rounded corners:
* **Start date** on the left edge.
* **Finish date** on the right edge.
* **A one-day event** will have rounded corners on all edges (when start date == end date).
* Each calendar day can has multiple states depending on what kind of day it is:
* **When enabled:**
* Regular day (_Basic/Black_ on a neutral _Basic/White_ background)
* Start date and finish dates (_Basic/White_ on a _Main/Main Dark_ blue background)
* Selected but neither start/nor end (black text on a light blue F\_eedback/Info/Light\_ F_eedback/Info/Light_ background)
* Today (_Basic/Black_ text on yellow _Indication/Current date_ background)
* **When disabled:**
* Regular day (_Basic/Gray 3_ text on a neutral white background)
* Start date (\_Basic/_G\_ray (_Basic/_G_ray 3_ text on a _gray#5_ background)
* Selected but neither start/nor end (\_Basic/_G\_ray (_Basic/_G_ray 4_ text on a \_Basic/_G\_ray _Basic/_G_ray 5_ background)
* Today (\_Basic/_G\_ray (_Basic/_G_ray 4_ text on yellow _Indication/Current date_ background)
<figure class="image op-uc-figure" style="width:50%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31095/content"></div></figure>
<figure class="image op-uc-figure" style="width:50%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31096/content"></div></figure>
#### Action bar
* The action bar has two actions:
* **Cancel button** (outlined/main), discards changes
* **Apply button** (filled/main), applies changes
### Anatomy
The date picker is built out of several components already described in our design system, and some new ones.
_**\[Updated visual to be added\]**_
### Visuals
**Regular scheduling**
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31800/content"></div></figure>
**Automatically scheduled, modification blocked with info banner**
_Info banner: Dates are derived from relations:_
* _**\[Updated visual to be added\]**_
**Manual scheduling with warning banner**
_Warning banner: relations are ignored:_
* _**\[Updated visual to be added\]**_
**Regular scheduling with info banner (project duration)**
_Info banner: Changing dates will affect project duration:_
* _**\[Updated visual to be added\]**_
**Regular scheduling with warning banner (related work packages affected)**
_Warning banner: Changing dates will affect dates of related packages (following or preceeding):_
* _**\[Updated visual to be added\]**_
### Simple Date Picker (single-day)
The simple date picker is for single-day items (like Milestones) only single _date_ field.
* The only difference with the regular work package date picker is that the unique date field is titled "Date" (no notion of start or finish dates).
* The selected date is rounded on all corners.
* The simple date picker can also have the information banner (with all the same states as the work package information date picker).
_**Note:**_
_The area to the right of the "Scheduling" and "Date" fields looks rather empty. This is a conscious decision in anticipation of other options that will come with later releases (involving automatic scheduling modes)._
**Simple date picker:**
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31801/content"></div></figure>
**Simple date picker with banner:**
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31802/content"></div></figure>
### Mobile version
The mobile version:
* Is displayed in a modal that takes almost the full available screen width.
* **\[open\]** Can we set a single value for the outside margins (1.25 or 1.5 REM, needs testing) or do we need to condition this on breakpoints?
* The start and finish dates will only display the date in ISO format (yyyy.mm.dd) and not our usual human-readable form that includes the day of the week (this is purely to save space).
* There is only one mini calendar (vs the two in our non-mobile version).
* The mobile date picker displays a simplified version of the banner:
* Without the left-side icon
* Without the second line of text (only the first line is displayed)
* With the usual "GANTT preview" button.
* The simple version of the mobile date picker:
* Has a single date field titled simply "Date"
* that takes 100% of the available width
* Can only allow picking a single date in the calendar (rounded on all corners)
**Mobile date-picker:**
* _**\[Updated visual to be added\]**_
**Mobile date-picker with banner:**
* _**\[Updated visual to be added\]**_
**Mobile simple date-picker (single-day):**
* _**\[Updated visual to be added\]**_
### Open Questions
* **\[open\]** Need to verify if the different information banners are exclusive, or if there can be multiple ones (in which case, we need to determine priority).
* There are two information banners that are exclusive and can not "clash with others"
* Automatically scheduled
* Manually scheduled
* For the three others, this is a proposition for a priority order for which one to show if there are multiple (only the highest one is displayed). Warnings naturally have more priority than information ones:
* Changing dates affects dates of other work packages
* ~~Change affects total project duration~~
* Available start/finish dates limited by relations
* see comment #3 for more concerns
* **\[open\]** How does the focus behaviour work together with the date selection mechanism? See bottom part of comment #3
* **\[open\]** How shall the modal close on mobile? Currently it is defined via a cancel button which is inconsistent to the mobile drop down behaviour we have for example for projects include.
### Out of scope
* This version of the date picker does not include two features that will come later (post 12.2):
* **Duration** and
* **Non-working days**
* These are described in <mention class="mention" data-id="41341" data-type="work_package" data-text="#41341">#41341</mention>.
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31798/content"></div></figure>
### **Acceptance criteria**
Clicking on a date field displays the date picker drop modal:
#### Overview
The date picker consists of these sections (see [Anatomy](https://community.openproject.org/#anatomy) below for design anatomy), each of which is described in more detail below:
* **An information/warning banner**
* **Scheduling option selection**
* **Start date and finish date**
* **The two-month mini-calendar**
* **Action bar**
#### Default behaviour
When the date picker is opened, a field is always in focus by default.
* When opened by clicking the "start date" field, the start date will be in focus by default.
* When opened by clicking the "finish date" field, the finish date will be in focus by default.
_(For information, when the unified date field is implemented, clicking on it:_
* _Will open the date picker with the start date in focus.)_
When all fields are cleared, and a date/day is clicked:
* That date will be considered a start date by default.
* However, if the user then clicks on a second date prior to that initially selected date, that second date will now be considered the start date, and the initial one the finish date.
* _This behaviour needs to be tested in implementaiton to ensure it "feels" right, especially when making a series of modficcations._
#### Warning/Information Banner
We use this banner to inform or warn the user when there is information contextual information.
* There can be two types of banners:
* An **information banner** has a blue background and is purely informational, to give the user additional context they might otherwise miss
* A **warning banner** has an orange background and indicates that changes to this work package may have destructive or unintended consequences (affect the dates/scheduling of other work packages)
* It consists of:
* an icon
* two-line message, the first in bold
* a "GANTT preview" button that, when clicked, opens up a GANTT preview in a new window that allows the user to view relations affecting this work package.
* This is a filtered work package list (table view + GANTT view) showing only work packages related to the "main" work package (the one for which the GANTT preview was requested).
* _**Open:** We might have to show some kind of message to inform the user that certain work packages might be invisible (filtered out, or no permission)._
* There are five identified cases in which this banner is displayed:
* **Information:** The dates are automatically derived from relations (and date input is disabled in regular mode)
* **Warning:** Manual scheduling is enabled so all existing work package relations are ignored.
* ~~**Information:** Changing the dates of this work package will affect the total project duration~~.
* **Warning:** Changing the dates of this work package will change the dates of related work packages
* **Information:** Available start and finish dates are limited by relations.
#### Regular/Manual Scheduling
* There are two modes
* **Regular** is the default scheduling mode where relations and project constraints are taken into account.
* **Manual** ignores work package relations and project constraints and functions as it does today when "manual scheduling" is checked.
* A helper icon in the label will display a tooltip with this text on hover :
* "Regular scheduling takes relations and project constraints into consideration, manual will ignore them."
#### Start Date and Finish Date
* There are two fields that use the new text field components of equal width:
* Start date
* Finish date
* The user is able to input dates either:
* by clicking on the dates on the mini-calendar (in the date picker modal)
* by inputting the dates manually in the text fields for start date and finish date in ISO format.
* Selecting a start date by clicking on a date or by inputting and pressing tab will move the focus to the finish date.
* On focus, the field is outlined in blue (focus style).
* The focus on the field also determines what is selected when the user clicks on a day in the calendar (i.e, clicking on the the start date field and then clicking on a date sets that date to the start date).
* **\[open\]** The visual format for displaying dates depends on the locale settings.
* Or we will use the ISO format everywhere. (to be discussed)
* ~~When in focus, the date text field should convert the date into an ISO format ("2022-03-31"). The user can then manually modify the date or enter a new date in this format.~~
* ~~On blur (focus removed), the display goes back to a more readable format (depending on locale, eg. "Thu 31.03.2022")~~
#### The two-month mini-calendar
The mini calendar allows the user to select start and end dates:
* Two months are displayed (current and next month)
* Clicking on backwards/forwards advances the calendar by a single month (eg. clicking on "forward" displays displays on the first calendar the month that was previously in the second calendar).
* **\[open\]** Is the change applied on blur (focus out) or directly on input?
* Today, entering date will "select" it immediately. We might retain this behaviour.
* When the date fields are empty:
* Clicking on a date on the calendar will set it as the start date.
* Hovering on any date _**after**_ that initially selected date:
* will give a "preview" of the end date (as in, all dates between the selected start date and this second date will be highlighted on hover).
* Clicking on a date will then set that as the finish date.
* Hovering on any date _before_ that initially selected date:
* will also give a "preview" of the period selected, but in considering that first date as the finish date.
* Clicking on a date will then set that second date as start date, and the initially selected date as the finish date.
* The start and finish dates field have "clear" buttons on focus that allow the user to clear that date (current behaviour).
* **\[open\]** If, in our design system, we decide to always show the clear button (x) even on blur, these fields will respect that.
* The start and finish dates are have rounded corners:
* **Start date** on the left edge.
* **Finish date** on the right edge.
* **A one-day event** will have rounded corners on all edges (when start date == end date).
* Each calendar day can has multiple states depending on what kind of day it is:
* **When enabled:**
* Regular day (_Basic/Black_ on a neutral _Basic/White_ background)
* Start date and finish dates (_Basic/White_ on a _Main/Main Dark_ blue background)
* Selected but neither start/nor end (black text on a light blue F\_eedback/Info/Light\_
* Today (_Basic/Black_ text on yellow _Indication/Current date_ background)
* **When disabled:**
* Regular day (_Basic/Gray 3_ text on a neutral white background)
* Start date (\_Basic/_G\_ray
* Selected but neither start/nor end (\_Basic/_G\_ray
* Today (\_Basic/_G\_ray
<figure class="image op-uc-figure" style="width:50%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31095/content"></div></figure>
<figure class="image op-uc-figure" style="width:50%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31096/content"></div></figure>
#### Action bar
* The action bar has two actions:
* **Cancel button** (outlined/main), discards changes
* **Apply button** (filled/main), applies changes
### Anatomy
The date picker is built out of several components already described in our design system, and some new ones.
_**\[Updated visual to be added\]**_
### Visuals
**Regular scheduling**
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31800/content"></div></figure>
_Info banner: Dates are derived from relations:_
* _**\[Updated visual to be added\]**_
**Manual scheduling with warning banner**
_Warning banner: relations are ignored:_
* _**\[Updated visual to be added\]**_
**Regular scheduling with info banner (project duration)**
_Info banner: Changing dates will affect project duration:_
* _**\[Updated visual to be added\]**_
**Regular scheduling with warning banner (related work packages affected)**
_Warning banner: Changing dates will affect dates of related packages (following or preceeding):_
* _**\[Updated visual to be added\]**_
The simple date picker is for single-day items (like Milestones) only single _date_ field.
* The only difference with the regular work package date picker is that the unique date field is titled "Date" (no notion of start or finish dates).
* The selected date is rounded on all corners.
* The simple date picker can also have the information banner (with all the same states as the work package information date picker).
_**Note:**_
_The area to the right of the "Scheduling" and "Date" fields looks rather empty. This is a conscious decision in anticipation of other options that will come with later releases (involving automatic scheduling modes)._
**Simple date picker:**
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31801/content"></div></figure>
**Simple date picker with banner:**
<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/31802/content"></div></figure>
### Mobile version
The mobile version:
* Is displayed in a modal that takes almost the full available screen width.
* **\[open\]** Can we set a single value for the outside margins (1.25 or 1.5 REM, needs testing) or do we need to condition this on breakpoints?
* The start and finish dates will only display the date in ISO format (yyyy.mm.dd) and not our usual human-readable form that includes the day of the week (this is purely to save space).
* There is only one mini calendar (vs the two in our non-mobile version).
* The mobile date picker displays a simplified version of the banner:
* Without the left-side icon
* Without the second line of text (only the first line is displayed)
* With the usual "GANTT preview" button.
* The simple version of the mobile date picker:
* Has a single date field titled simply "Date"
* that takes 100% of the available width
* Can only allow picking a single date in the calendar (rounded on all corners)
**Mobile date-picker:**
* _**\[Updated visual to be added\]**_
**Mobile date-picker with banner:**
* _**\[Updated visual to be added\]**_
**Mobile simple date-picker (single-day):**
* _**\[Updated visual to be added\]**_
### Open Questions
* **\[open\]** Need to verify if the different information banners are exclusive, or if there can be multiple ones (in which case, we need to determine priority).
* There are two information banners that are exclusive and can not "clash with others"
* Automatically scheduled
* Manually scheduled
* For the three others, this is a proposition for a priority order for which one to show if there are multiple (only the highest one is displayed). Warnings naturally have more priority than information ones:
* Changing dates affects dates of other work packages
* ~~Change affects total project duration~~
* Available start/finish dates limited by relations
* see comment #3 for more concerns
* **\[open\]** How does the focus behaviour work together with the date selection mechanism? See bottom part of comment #3
* **\[open\]** How shall the modal close on mobile? Currently it is defined via a cancel button which is inconsistent to the mobile drop down behaviour we have for example for projects include.
### Out of scope
* This version of the date picker does not include two features that will come later (post 12.2):
* **Duration** and
* **Non-working days**
* These are described in <mention class="mention" data-id="41341" data-type="work_package" data-text="#41341">#41341</mention>.