Preface

TimeInterval is an Open Source project of VivaRado.

Introduction

The TimeInterval interface aims to simplify the process of date and time selection, and offer more granularity in formatting.

Contributors:

• VivaRado [email protected]
• Andreas Kalpakidis
• Madina Akhmatova

---

Profile

_{Introduction / Profile}

• Company: VivaRado LLP
• Designer: Andreas Kalpakidis
• Management: Madina Akhmatova

---

Project Overview

_{Introduction / Project Overview}

• Project Name: TimeInterval
• Code Name: tintvl
• Proposal Date: 01/04/2025

---

Design

The source consists of TimeInterval, DateFormatParse, Assertions and Utils.

---

Interface

_{Design / Interface}

We simplify the process of time selection by offering multi input methods. You can input the time directly to the main input fields or adjust the units in a dropdown. Navigation is made easy via keyboard arrows that allow for quick adjustments. We offer assertions to maintain the validity of date input, may that be in the main input field or the time unit input fields in the dropdown. Labels simplify the process, by informing the user for the name of the day and month, in a compact fashion.

Day Month Year:

Month Year:

Twelve hour clock:

Twenty-four hour clock:

---

Composition

_{Design / Interface / Composition}

The src contains ESM (ECMAScript modules) only for the JS, the structural CSS is located in the src/timeinterval.css file, and the thematic CSS in src/theme.css, you can do without the thematic, or roll your own.

---

TimeInterval

_{Design / Interface / TimeInterval}

---

Usage

_{Design / Interface / TimeInterval / Usage}

Initiating the TimeInterval user interface by including the TimeInterval class to your page, or by importing it in a script:

<script src="./src/timeinterval.esm.js" type="module"></script>

import {TimeInterval} from './src/timeinterval.esm.js'

---

Parameters

_{Design / Interface / TimeInterval / Parameters}

Pass the parameters object when initiating a new class.

var element = document.querySelector(".timeinterval")
var parameters = {
	format: "HH:mm",
	start_time: "22:21",
	range: true,
	ast_intvl: true,
	ast_value: true,
	ast_silent: false
}
new TimeInterval(element, parameters);

---

Parameter Overview

A description of each parameter:

format [ String ]

Provide the date format string, supported formats: 'HH:mm' 'hh:mm a' 'MM/yyyy' 'dd/MM/yyyy' 'dd/mm'

start_time [ String ]

A string representation of a date, adhering to the provided format, used as an initiation time.

range [ Bool ]

Show range button. If range is not needed, provide only one HTML input field and set to range:false.

ast_intvl [ Bool ]

Assert interval difference. Asserts if the first input field date occurrence preceeds the second.

ast_value [ Bool ]

Assert date value. Asserts the quality of provided date representation strings.

ast_silent [ Bool ]

Assertions still happen unless turned off above (ast_intvl, ast_value), but will be silenced and there will be no error reporting on the client.

upstream_input [ Bool ]

Prevent wrapped input fields being editable.

labels [ Bool ]

Show labels for time units.

aware_label [ Bool ]

Show the name of days and months, inplace of generic labels, where applicable. Requires labels:true. Labels come from ./src/dfp.js specific variables _days, _mths.

labels_days [ Array ]

You can provide an array of day names for localisation.

labels_mths [ Array ]

You can provide an array of month names for localisation.

keyboard_arrow [ Bool ]

Allow usage of keyboard arrows for, input selection and value input.

---

Adjustments

_{Design / Interface / TimeInterval / Adjustments}

The ./src/timeinterval.css contains settings for various parts of the appearance of the wrapper dropdown:

:root {
  --trwd: 5rem;    /* width of time_input controllers inside the wrap */
  --trpd: 0.5rem;  /* space between time_input controllers */
  --trwp: 1rem;    /* padding around wrap */
}

---

Interactivity

_{Design / Interface / TimeInterval / Interactivity}

An overview of interface interactivity.

---

Keyboard Controls

Left and Right to select wrapper input field, top and bottom to increase and decrease value.

⮜ Navigate to the left wrapped input.

⮞ Navigate to the right wrapped input.

⮝ Increase value of current wrapped input.

⮟ Decrease value of current wrapped input.

---

Desired Behaviours

• Click on main input field should show the dropdown wrapper.
• Input of appropriatelly formated date should update the value.
• Input of appropriate date into wrapper input fields should update the input value, and upstream to the main input field.
• Left Click on the up and down arrows should update the input value, and upstream to the main input field.
• Left Click and hold should increment value in the input field and upstream to the main input field on release.
• Right Click on the up and down arrows is dissabled.
• Click anywhere other than the main input field or active wrapper should close any active wrappers.
• Pressing the Escape key, while on main input field focus, should close any active wrappers.
• Left and Right keyboard arrows should select wrapper input fields.
• Tab and Shift Tab should select wrapper input fields.
• Up and Down keyboard arrows should increase and decrease the wrapper input field value, and upstream to the main input field.
• Click on Range Toggle button should bring in the second main input field.

---

Functions

_{Design / Interface / TimeInterval / Functions}

Here is an overview of the TimeInterval function(s):

constructor ( trg, cfg )

param trg: Element or Nodelist
param cfg: Object (Parameters)

---

Initiates building of the interface, initiates interactivity listeners, provides data structures and defaults.

build ( element, inx )

param element: Element
param inx: Integer Index

---

Formulates the HTML around the targeted elements. Provides access to public functions ( hide, show, setDate )

getControlInput ( element )

param element: Element

---

updates: this.ctpi with Element

---

Updates this.ctpi holding current interacted wrapper input element.

clearClass ( cls )

param cls: String (class without dot)

---

Removes class from elements with given class cls.

calendarDays ()

returns: Integer number of days in month.

isSubseq ( el_inp )

param el_inp: Element

---

returns: Bool

---

Returns true if main input provided is subsequent, false if it is the first.

controlsShow ( el )

param el: Element

---

Show wrapper controls dropdown.

controlsHide ( el )

param el: Element

---

Hide wrapper controls dropdown.

padValue ( sym, el )

param sym: String Token [ ye, mo, da, ho, mn, se, ml, me ]
param el: Element

---

returns: String

---

Pads integer value with zeros based on the unit symbol.

determineValue ( tx )

param tx: String Set Token [ ye_tx, mo_tx, da_tx, ho_tx, mn_tx, se_tx, ml_tx, me_tx ]

---

returns: String

---

Returns padded value given set token.

dateContract ( frm )

param frm: String Specification Format

---

Turn Date Object this.prm.dto to Date String given Spec. Format.

dateExpand ( date_string )

param date_string: String Representation of Date

---

returns: String

---

Turn Date String to Date Object this.prm.dto.

calcDate ( dir )

param dir: String [prev, next, none]

---

updates: this.prm.dto[tkn]

---

Calculates increase or decrease of date unit (tkn) of active wrapper input field, given direction.

populateWrapperInputs ()

Adds this.prm.dto values to wrapper inputs according to their tokens.

dateDisplay ()

Displays this.prm.dto date to main inputs and wrapper inputs.

assertDateTokens ()

Asserts all activeTokens of given wrapper inputs, for valid date values.

resolveDate ( start_time, target, stream, direction )

param start_time: String Representation of Date.
param target: Element.
param stream: String [upstream, downstream, direct].
param direction: String [prev, next, none]

---

Main function used to resolve the date.

A1.  Define dtstr with start_time if that is available, 
     if not and input is empty, define it with the current time, 
     otherwise leave the current value.
A2.  Assert date uniformity, the values provided are checked, 
     for exceeding max allowed unit length.
A3.  Date is expanded from string to object.
A4.  Date is calculated, increased, decreased or left as is.
A5.  Every token in the date object is asserted separatelly. 
     See assertion functions for assertDate.
A6.  Update this.prev_val with valid value.
A7.  Contract date to string.
A8.  Assert range if range assertion conditions are met.
A9.  Display date on main input field and wrapper input fields.
A10. Return all assertion messages if not silenced.

startTimeInterval ( e , date_string, stream)

param e: Event
param date_string: String Representation of Date.
param stream: String [upstream, downstream, direct].

---

Event function, for date change interaction requests.

arrowSelect ( e, dir )

param e: Event.
param dir: String [left, right].

---

Picks wrapper input on left or right keyboard arrow press.

onHold ( self, e )

param self: this.
param e: Event.

---

Event function, for when press and hold event (keyboard or press) is requested, initiates timeouts and intervals.

onRelease ( self, e )

param self: this.
param e: Event.

---

Event function, for when release event (keyboard or press) is requested, clears timeouts and intervals.

awareLabelUpdate ( tgt )

param tgt: Element.

---

Updates labels with day name and month name, where applicable.

wrapperInput ( tgt , sym )

param tgt: Element.
param sym: String Token [ ye, mo, da, ho, mn, se, ml, me ].

---

Event function, for date change interaction requests coming from wrapper inputs.

interact ( elem )

param elem: Element.

---

Set Events on main and subsequent inputs, wrapper inputs and wrapper control arrows.

B1.  Show Controls on click or focus on main inputs.
B2.  Set Events on wrapper input arrows.
B3.  Dissavle context menu on arrows.
B4.  Initiate onHold on mousedown.
B5.  Initiate onRelease on mouseup.
B6.  On mouse leave reset holdActive and timeouts.
B7.  On focus send main input value downstream,
     to wrapper inputs.
B8.  Store the value in prev_val for restoration,
     in case of failed assertions.
B9.  Backspace and Delete
B10. On enter key assume client requests value update, 
     initiate downstream.
B11. On escape assume clients requests cancelation, hide wrapper.
B12. On change of the values of the wrapper inputs, 
     initiates wrapperInput, otherwise leave initial value.
B13. On focus et active class on wrapper input.
B14. Sanitize input to numpad numbers, number keys, 
     dissalow characters, allow ctrl or meta, 
     ignore backspace, delete, and left right arrows.
B15. Keyboard arrow navigation.

---

Substructure

_{Design / Substructure}

The interface is supported with dateformatparse for date parsing/formatting and assertions for date uniformity and validity.

---

DateFormatParse

_{Design / Substructure / DateFormatParse}

For reasons of self containment we provide the DateFormatParse. This could be substituted by another, more comprehensive date parsing and formatting library.

---

Usage

_{Design / Substructure / DateFormatParse / Usage}

Used in TimeInterval to Format and Parse:

"HH:mm"          // 22:16
"hh:mm a"        // 10:16 PM
"MM/yyyy"        // 07/2025
"dd/MM/yyyy"     // 02/07/2025
"dd/mm"          // 02/07

Standard Behaviour:

formatDate( "MMM dd, yyyy", new Date()   ) // returns string
parseDate ( "05/12/2450"  , "MM/dd/yyyy" ) // returns date object

"h:mm a"                       // 8:46 PM
"MM/dd/yyyy"                   // 02/17/2020
"MMM dd, yyyy"                 // Feb 17, 2020
"EEE, MMM d, ''yy"             // Mon, Feb 17, '20
"hh 'o''clock' a, X"           // 08 o'clock PM, -0600
"yyyyMMdd'T'HHmmssXX"          // 20200217T204746-0600
"yyyy-MM-dd'T'HH:mm:ssXXXX"    // 2020-02-17T20:47:46-06:00
"hh 'o''clock' a, zzzz"        // 12 o'clock PM, Pacific Daylight Time

"O"        // GMT-8
"OOOO"     // GMT-08:00 
"x"        // -08 		// +00 if offset is zero
"xx"       // -0800 	// <<
"xxx"      // -08:00 	// <<
"xxxx"     // -0800 	// <<
"xxxxx"    // -08:00 	// <<
"X"        // -08 		// "Z" if offset is zero
"XX"       // -0800 	// <<
"XXX"      // -08:00 	// <<
"XXXX"     // -0800 	// <<
"XXXXX"    // -08:00 	// <<
"zzzz"     // Pacific Standard Time

---

Functions

_{Design / Substructure / DateFormatParse / Functions}

Here is an overview of the Reports functions:

_TZ ( date, symb )

param date: Date Object.
param symb: Number.

---

Display strength value on strength bar as percentage.

_h ( res, mtl )

param res: Integer, Value Length.
param mtl: Integer, Match Length.

---

Parse Hours

_a ( res, mtl )

param res: Integer, Value Length.
param mtl: Integer, Match Length.

---

Parse Meridiem

_M ( res, mtl )

param res: Integer. Value Length
param mtl: Integer. Match Length

---

Parse Month

_E ( res, mtl )

param res: Integer, Value Length.
param mtl: Integer, Match Length.

---

Parse Day Name

replaceCoverage ( fStr, iArr )

param fStr: String Date format.
param iArr: Array Matches.

---

Display feedback as alerts.

pads ( str, mt )

param str: String.
param mt: Integer.

---

Pad str by mt.

kfn ( mtc, kwds, rk = false )

param mtc: matches Array.
param kwds: keywords Object.
param rk: Boolean.

---

Keyword Object retrieval.

formatDate ( fStr, dObj )

param fStr: String Date format.
param dObj: Date Object.

---

Format a Date Object according to a Date format string.

assertDateUniform ( dStr, fStr )

param dStr: String Representation of Date.
param fStr: String Date format.

---

returns: Bool.

---

Assert date string uniformity by comparing the maximum length of all matched symbols from the fStr, with the length of the provided dStr, ignoring non relevant characters.

parseDate ( dStr, fStr, obj )

param dStr: String Representation of Date.
param fStr: String Date format.
param obj: Bool.

---

returns: Date Object if obj is false.
returns: dto Object if obj is true.

---

Parse a date string given format. Return Date Object or dto Object.

calcUnit ( date, unit, quant )

param date: Date Object.
param unit: String [days, minutes].
param quant: Number.

---

Rudamentary unit calculation on Date Object.

---

Assertions

_{Design / Substructure / Assertions}

Contains the assertRange and assertDate main assertions for TimeInterval.

---

Functions

_{Design / Substructure / Assertions / Functions}

Here is an overview of the Assertion functions:

assertRange ( timeinterval, cnav, subseq )

param timeinterval: TimeInterval Class Instance
param cnav: Element
param subseq: Bool

---

Returns: Object { verdict: Bool, messages: Array }

---

Assert if applicable, for the main input elements, that the subsequent input element, does not contain a time value smaller or equal to the first input element.

assertDate ( timeinterval, date_str, sym )

param timeinterval: TimeInterval Class Instance
param date_str: String Representation of Date
param sym: String [ ye, mo, da, ho, mn, se, ml, me ]

---

Returns: Object { verdict: Bool, messages: Array }

---

Assert date for various conditions.

C1.  Assert the a date string being parseable, 
C2.  Assert the symbol of a date string for maximum digit length 
     and maximum unit length - if day calculate max days in month, 
C3.  Assert for minimum year, 
C4.  Assert for value overflow at 24 hours, 
     Assert for value overflow at 60 minutes.

---

Production

To work on extending this module a few things are provided:

Run in browser with reload allong with gulp watch:

npm run dev

Just build with gulp

npm run build

Test the server side functions

npm run test

---

Installation

TimeInterval does not have any dependencies, other than those for development (--save-dev).

You could substiture date parsing and formatting with a more complete, library.

To install:

npm install

---

Glossary

ye: year.
mo: month.
da: day.
ho: hour.
mn: minute.
se: second.
ml: millisecond.
me: meridiem.
nm: name month.
nd: name day.

---

Reference

Date Object
Date Field Symbol Table

---