Skip to content

Commit

Permalink
feat: changes for datetimepicker component
Browse files Browse the repository at this point in the history
  • Loading branch information
@shiprarawal
shiprarawal committed Aug 26, 2024
1 parent 1fbf670 commit 9c4fd9f
Show file tree
Hide file tree
Showing 11 changed files with 417 additions and 0 deletions.
1 change: 1 addition & 0 deletions content/body/acknowledgements.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
</li>
<li>Sahil Singh for unit tests for the <a href="input-mask.php">input mask component</a>.</li>
<li><a href="https://www.useragentman.com/">Zoltan Hawryluk</a> for starting the Enable project to begin with.</li>
<li><a href="https://github.com/shiprarawal">Shipra Rawal</a> for the <a href="./infographic.php">accessible infographics</a> and <a href="./datetimepicker.php">accessible datetime picker</a> component.</li>
</ul>

<h2>Code Used By Enable</h2>
Expand Down
296 changes: 296 additions & 0 deletions content/body/datetimepicker.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,296 @@
<p>
An Accessible DateTimePicker is a user interface tool that provides clear labels, adjustable settings, and support for
various assistive technologies. The Accessible DateTimePicker
ensures that selecting and managing date and time is both intuitive and inclusive for everyone.
</p>
<p>
In HTML5, they can be implemented by setting the type of input field as <code>datetime-local</code>.
In ARIA, they can be implemented with the Aria properties and a bit of JavaScript.
</p>
<p>
This is one of the uncommon instances where the native HTML5 version of datetimepicker is not accessible in most web
browsers.
The testing results in different browsers are also explained in this <a
href="https://www.hassellinclusion.com/blog/input-type-date-ready-for-use/" target="_blank">article.</a>
Consequently, the custom datetimepicker is the preferred solution.
</p>

<h2 id="aria-combobox" tabindex="-1">Custom date and time control </h2>

<?php includeStats([
"isForNewBuilds" => true,
"comment" =>
"This datetimepicker works better with screen readers than the native HTML5 version",
]); ?>
<?php includeStats([
"isNPM" => true,
]); ?>

<p>
This is a slightly refactored version of
<a href="https://flatpickr.js.org/" target="_blank">the datetime picker example at
flatpickr.js.org</a>. Added was a few extra aria-describedby so that the screen reader announces the different
inputs of time field.
</p>
<div class="enable-example">
<div id="example1">
<div class="datetimepicker__select-wrapper">
<div class="datetimepicker__select"> <!-- Dropdown to select language -->
<label for="datetimepicker-language-select">Choose language:</label>
<select id="datetimepicker-language-select">
<option value="en">English</option>
<option value="fr">French</option>
</select>
</div>
<div>
<div>
<label>
<span class="datetimepicker__select-label">Enter the travel date and time</span>
<input class="datetimepicker" aria-describedby="traveldatetime">
<div id="traveldatetime" class="sr-only">
The date and time format is YYYY-MM-DD HH:MM.
</div><!--datetimepicker input-->
</label>
</div>
</div>
</div>
<span id="hour-description" class="datetimepicker__desc">Time Field, Please enter hour </span>
<span id="minute-description" class="datetimepicker__desc">Time Field, Please enter minute </span>
<span id="time-description" class="datetimepicker__desc">Time Field, Please select AM or PM </span>
</div>
</div>
<?php includeShowcode("example1"); ?>
<script type="application/json" id="example1-props">
{
"replaceHtmlRules": {},
"steps": [{
"label": "Add a dropdown to select the language preference",
"highlight": "language-select",
"notes": "In this example, there are only two language options. However, there are many locales available and details can be found <a href=\"https://flatpickr.js.org/localization/\" target=\"_blank\">here.</a>"
},
{
"label": "Add an input and provide a class or id to it. The same class or id needs to be passed in the javascript.",
"highlight": "datetimepicker",
"notes": "Once you have got the instance of the datepicker, you can easity access it's properties."
},
{
"label": "Add few span tags having the description of the time field. It gets announced when use selects the hour, minute or AM/PM",
"highlight": "hour-description",
"notes": "The aria-describedby property is set using the javascript. The id allocated to the span attributes is assigned dynamically to the time input."
}
]
}
</script>

<h3 id="npm-instructions">Installation Instructions</h3>
<p>The instructions for installing a flatpickr module are available <a href="https://flatpickr.js.org/getting-started/"
target="_blank">here</a></p>

<h3>Keyboard Support</h3>
<h4>Datetime picker: Open and close dialog</h4>
<table class="datetimepicker__table">
<thead>
<tr>
<th>Key</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>Tab and Enter</td>
<td>
When the datetime picker field receives the focus, it opens the datetime picker dialog. Use the <code>Up</code>
or <code>down</code> arrow key to select the current date.
Press <code>Enter</code> key to confirm the date selection.
</td>
</tr>
<tr>
<td>Esc</td>
<td>Closes the dialog and returns focus to the "Select Date" field. Press <code>Enter</code> to reopen the
Datetime picker dialog.</td>
</tr>
</tbody>
</table>
<h4>Date Picker Dialog: Navigate different dates, month & year</h4>
<table class="datetimepicker__table">
<thead>
<tr>
<th>Key</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>Up Arrow</td>
<td>
Moves focus to the same day of the previous week.
</td>
</tr>
<tr>
<td>Down Arrow</td>
<td>Moves focus to the same day of the next week.
</td>
</tr>
<tr>
<td>Right Arrow</td>
<td>
Moves focus to the next day.
</td>
</tr>
<tr>
<td>Left Arrow</td>
<td>
Moves focus to the previous day.
</td>
</tr>
<tr>
<td>
<ul>
<li>Mac (Control + Command/Option/Shift + Left arrow key)</li>
<li>Windows (Control + Shift + Left arrow key)</li>
</ul>
</td>
<td>Changes the grid of dates to the previous month.</td>
</tr>
<tr>
<td>
<ul>
<li>Mac (Control + Command/Option/Shift + Right arrow key)</li>
<li>Windows (Control + Shift + Right arrow key)</li>
</ul>
</td>
<td>Changes the grid of dates to the next month.
</td>
</tr>
<tr>
<td>
<ul>
<li>Mac (Control + Command/Option/Shift + Down arrow key)</li>
<li>Windows (Control + Shift + Down arrow key)</li>
</ul>
</td>
<td>Changes the grid of dates to the previous year.
</td>
</tr>
<tr>
<td>
<ul>
<li>Mac (Control + Command/Option/Shift + Up arrow key)</li>
<li>Windows (Control + Shift + Up arrow key)</li>
</ul>
</td>
<td>Changes the grid of dates to the next year.
</td>
</tr>
</tbody>
</table>

<h4>Date Picker Dialog: Select time</h4>
<table class="datetimepicker__table">
<thead>
<tr>
<th>Key</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>Enter</td>
<td>
Press the Enter key to activate the selected date. It automatically takes focus to Time field. Press <code>Enter</code> again to select the time. Anytime to move focus out of the time field, press the <code>Shift + Tab</code> key.
</td>
</tr>
</tbody>
</table>

<h2>Using HTML5 date and time control </h2>

<?php includeStats([
"doNot" => true,
"comment" =>
"This does not work with assistive technologies in most web browsers.",
]); ?>
<p>
Ironically, this seems to be inaccessible compared to the ARIA version. Because of the below reasons, it is one of the
cases where ARIA works better.
</p>
<ol>
<li>Inconsistent Browser Support and Visual Design:
<p>
The appearance of the native date-time picker can vary significantly between browsers and operating systems.
For instance, the date and time control feature looks quite different in Firefox (version 129),
whereas in Safari (version 16.6), the placeholder text is grayed out and the calendar icon is missing.
Moreover, in Safari, when users try to adjust the year field, the value can range from 0001 to 275760.
Despite the accepted format being YYYY, users can still input up to six digits in the year field, and
the focus does not automatically shift to the next field.
These inconsistencies can create a confusing user experience, particularly for individuals with cognitive disabilities.
</p>
</li>
<li>Validation and Error Handling:
<p>
Since users can enter an invalid date via the keyboard,
incorporating custom validation and error handling may be crucial to ensure that all users clearly understand what is required.
</p>
</li>
<li>Presentation format:
<p>
The date is displayed differently across various operating systems. On a Mac, the format in Chrome (version 127),
Safari (version 16.6), and Firefox (version 129) is YYYY-MM-DDThh:mm
. In contrast, on Windows, the format in Chrome (version 127) and Firefox (version 129) is mm/dd/yyyy hh:mm.
</p>
</li>
<li>Keyboard Navigation:
<p>
Users who rely on keyboard navigation for forms might struggle with the date-time picker.
Certain implementations lack straightforward keyboard navigation, making it challenging for users to select dates and times without using a mouse.
For example, if a user is navigating using only the keyboard on Chrome (version 127) on a Mac, the focus may not shift to the calendar icon that opens the date-time picker dialog,
leaving the user with no keyboard-based option to access the dialog and only allowing date entry.
</p>
</li>
<li>Lack of Customization:
<p>
The native control does not provide much flexibility in terms of styling or behavior customization.
This can make it difficult to match the control with the overall design and accessibility requirements of any
website.
</p>
</li>
<li>Screen Reader Compatibility:
<p>
Certain screen readers might not correctly convey the input type or offer an intuitive interaction method with the date-time picker.
This can hinder users who rely on screen readers from effectively understanding and using the control.
For instance, when using VoiceOver with Chrome on Mac, if the user enters the date and then focuses on the hour field,
VoiceOver might announce something like '-9.1 %, Hours Enter the travel (date and time).'
This confusing negative percentage can disorient the user.
</p>
</li>
</ol>
<div id="datetimepicker-example" class="enable-example">
<label for="traveldatetime">Enter the travel (date and time):</label>
<input type="datetime-local" id="traveldatetime" name="traveldatetime" aria-describedby="traveldatetime-desc">
<div id="traveldatetime-desc" class="sr-only">
Enter the date and time in the format YYYY-MM-DDTHH:MM. This format is standard, but your browser or operating system might display it differently.
</div>
</div>
<?php includeShowcode("datetimepicker-example"); ?>

<script type="application/json" id="datetimepicker-example-props">
{
"replaceHtmlRules": {},
"steps": [{
"label": "Create label for input tag.",
"highlight": "for",
"notes": "Just like any other form element, this needs a proper label."
},
{
"label": "Give keyboard instructions using aria-describedby.",
"highlight": "aria-describedby",
"notes": "Since the format of the date and time may not be localized according to the user's regional settings, these instructions may help some screen reader users use this component properly."
},
{
"label": "Set up the input type as datetime-local",
"highlight": "datetime-local",
"notes": "Note that input type datetime-local is required when you need both date and time input together. Otherwise input type as 'date' or 'time' could be used when you only need the user to input a date or time."
}
]
}
</script>
35 changes: 35 additions & 0 deletions content/bottom/datetimepicker.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<!-- classList polyfill for IE9 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/classlist/1.2.20171210/classList.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/flatpickr"></script>
<script src="https://npmcdn.com/flatpickr/dist/l10n/fr.js"></script>
<script>
function initializeFlatpickr(language) {
var fp = flatpickr(".datetimepicker", {
enableTime: true,
// disableMobile: true, // By default, Flatpicker shows the native HTML5 datepicker on mobile devices. To change this behavior and maintain a consistent appearance across all devices, set this property to true.
// allowInput:true, // allows the user to enter date using keyboard
dateFormat: "Y-m-d H:i",
locale: language === 'fr' ? 'fr' : 'default', // Set locale based on language
onReady: function(selectedDates, dateStr, instance) {
// Adding aria-label to the time input fields
const timeContainer = instance.calendarContainer.querySelector(".flatpickr-time");
if (timeContainer) {
const hourInput = timeContainer.querySelector("input.flatpickr-hour");
const minuteInput = timeContainer.querySelector("input.flatpickr-minute");
const ampmInput = timeContainer.querySelector("input.flatpickr-am-pm"); // for 12-hour format
if (hourInput) hourInput.setAttribute("aria-describedby", "hour-description");
if (minuteInput) minuteInput.setAttribute("aria-describedby", "minute-description");
if (ampmInput) ampmInput.setAttribute("aria-label", "AM/PM");
}
}
});
}
initializeFlatpickr('en');
// Listen for changes on the language dropdown
document.getElementById('datetimepicker-language-select').addEventListener('change', function(event) {
const selectedLanguage = event.target.value;
// Re-initialize Flatpickr with the new language
initializeFlatpickr(selectedLanguage);
});
</script>
2 changes: 2 additions & 0 deletions content/head/datetimepicker.php
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<link rel="stylesheet" type="text/css" href="css/datetimepicker.css" >
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/flatpickr/dist/flatpickr.min.css">
33 changes: 33 additions & 0 deletions css/datetimepicker.css
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
.datetimepicker__select-wrapper {
display: flex;
justify-content: space-around;
align-items: center;
}
.datetimepicker__select-label {
display: block;
}
.datetimepicker__desc {
display: none;
}
.datetimepicker__table {
border-collapse: collapse;
width: 100%;
}
.datetimepicker__table th {
background-color: #d0e1f1;
width: 50%;
}
.datetimepicker__table td,
.datetimepicker__table th {
border: 1px solid #dddddd;
text-align: left;
padding: 0.625rem;
}
@media only screen and (min-width: 1px) and (max-width: 719px) {
.datetimepicker__select-wrapper {
flex-direction: column;
}
.datetimepicker__select {
padding-bottom: 1.25rem;
}
}
Binary file added images/main-menu/datetimepicker.webp
View file
Binary file not shown.
Binary file added images/posters/datetimepicker.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 9c4fd9f

Please sign in to comment.