@ohos-ports/flowbite-datepicker 2.0.0-beta.0

package/docs/i18n.md

@@ -0,0 +1,99 @@
+# Internationalization (i18n)
+
+Internationalization of Datepicker is done by adding languages' locales (month and day names, button labels, date format and start of the week) to `Datepicker.locales`.  
+`en`:_English (US)_ is the pre-installed default language and also used as the fallback language.
+
+> The package includes locale files taken from [bootstrap-datepicker](https://github.com/uxsolutions/bootstrap-datepicker).
+
+## Adding languages
+
+Import the ones you need and merge them with `Datepicker.locales`.
+
+```javascript
+import Datepicker from 'path/to/node_modules/vanillajs-datepicker/js/Datepicker.js';
+import es from 'path/to/node_modules/vanillajs-datepicker/js/i18n/locales/es.js';
+import fr from 'path/to/node_modules/vanillajs-datepicker/js/i18n/locales/fr.js';
+import zhCN from 'path/to/node_modules/vanillajs-datepicker/js/i18n/locales/zh-CN.js';
+
+Object.assign(Datepicker.locales, es, fr, zhCN);
+```
+
+_Or if you use a bundler that supports [package entry points](https://nodejs.org/api/packages.html#packages_package_entry_points) (e.g. [Rollup](https://rollupjs.org/) with [node-resolve](https://github.com/rollup/plugins/tree/master/packages/node-resolve) plugin v8.4+, [webpack](https://webpack.js.org/) v5+)_
+
+```javascript
+import Datepicker from 'vanillajs-datepicker/Datepicker';
+import es from 'vanillajs-datepicker/locales/es';
+import fr from 'vanillajs-datepicker/locales/fr';
+import zhCN from 'vanillajs-datepicker/locales/zh-CN';
+
+Object.assign(Datepicker.locales, es, fr, zhCN);
+```
+
+##### for browser
+
+Load the locale files you need after Datepicker
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/js/datepicker-full.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/js/locales/es.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/js/locales/fr.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/js/locales/zh-CN.js"></script>
+```
+
+### Custom locale
+
+If needed, you can create your custom locale file by modifying the following template.
+
+```javascript
+/**
+ * English translation
+ */
+export default {
+  en: {
+    days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
+    daysShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
+    daysMin: ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"],
+    months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
+    monthsShort: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+    today: "Today",
+    clear: "Clear",
+    titleFormat: "MM y",
+    format: "mm/dd/yyyy",
+    weekStart: 0
+  }
+};
+```
+> You can omit properties that can fallback to `en`:_English (US)_.
+>  
+> **for browser:**
+> ```javascript
+> /**
+>  * English translation
+>  */
+> (function () {
+>   Datepicker.locales.en = {
+>     //... same properties as the above 
+>   }
+> })();
+> ```
+
+
+Locale must be named with language code. The code can be arbitrary, but should comply with [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag).
+
+
+## Text Direction
+
+Text direction handling of Datepicker is mainly done by stylesheet and completely separated from its language configuration.
+
+The picker element is styled to follow the container element's text direction. If the direction of the associated input field is different from it, date picker automatically detects the difference and sets the picker element's `dir` attribute so that the direction matches the input field's.
+
+> **When customizing the prev/next button**  
+>
+> The default of the prev/next button arrows are a pair of a parenthesis variant, which automatically flip according to text direction. If you customize the arrows with something other than parenthesis characters, you may need to add a style like below to your project's CSS in order for the arrows to flip automatically.
+>
+> ```css
+> [dir="rtl"] .datepicker-controls .prev-btn,
+> [dir="rtl"] .datepicker-controls .next-btn {
+>     transform: scaleX(-1);
+> }
+>```

package/docs/index.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>vannilajs-datepicker - Vanilla JS datepicker for Bulma and other CSS frameworks</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="A vanilla JavaScript remake of bootstrap-datepicker for Bulma and other CSS frameworks">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'vanillajs-datepicker',
+      repo: 'https://github.com/mymth/vanillajs-datepicker',
+      loadSidebar: true,
+      subMaxLevel: 4,
+      auto2top: true,
+    };
+  </script>
+  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
+  <script src="//unpkg.com/prismjs/components/prism-scss.min.js"></script>
+</body>
+</html>

package/docs/options.md

@@ -0,0 +1,354 @@
+# Options
+
+There are 2 kinds of config options: the Datepicker options and the DateRangePicker options. The former are for `DatePicker` object and the latter are for `DateRangePicker` object.
+
+Datepicker options can be used with date range picker. And when doing so, you can pass them mixing with DateRangePicker options into one "options" object.
+
+> Datepicker options passed to date range picker are applied to its start- and end-date pickers.
+
+Aside from a couple of exceptions, config options can be updated dynamically using the `setOptions()` method.
+
+### Datepicker Options
+
+#### autohide
+- Type: `Boolean`
+- Default: `false`
+
+Whether to hide the date picker immediately after a date is selected.
+
+> Not available on inline picker.
+
+#### beforeShowDay
+- Type: `Function`
+- Default: `null`
+
+Function to customize the day cells in the days view. The function is called when each day cell is rendered.
+
+- **function**
+  - Arguments:
+    - `date`: {`Date`} - Date associated with the cell
+  - Return:
+    - {`Object`} - Things to customize. Available properties are:
+      - `enabled`: {`Boolean`} - whether the cell is selectable
+      - `classes`: {`String`} - space-separated additional CSS classes for the cell element
+      - `content`: {`String`} - HTML for the cell element's child nodes
+    - {`String`} - additional classes — same as returning `{ classes: additionalClasses }`
+    - {`Boolean`} - whether the cell is selectable — same as returning `{ enabled: isSelectable }`
+
+```javascript
+function (date) {
+    let isSelectable, additionalClasses, htmlFragment;
+    //...your customization logic
+    
+    return {
+        enabled: isSelectable,
+        classes: additionalClasses,
+        content: htmlFragment,
+    };
+    // Or
+    return additionalClasses;
+    // Or
+    return isSelectable;
+}
+```
+
+#### beforeShowDecade
+- Type: `Function`
+- Default: `null`
+
+Function to customize the decade cells in the decades view. The function is called when each decade cell is rendered.
+> See [`beforeShowDay`](#beforeShowDay) for the function details.
+
+#### beforeShowMonth
+- Type: `Function`
+- Default: `null`
+
+Function to customize the month cells in the months view. The function is called when each month cell is rendered.
+> See [`beforeShowDay`](#beforeShowDay) for the function details.
+
+#### beforeShowYear
+- Type: `Function`
+- Default: `null`
+
+Function to customize the year cells in the years view. The function is called when each year cell is rendered.
+> See [`beforeShowDay`](#beforeShowDay) for the function details.
+
+#### buttonClass
+- Type: `String`
+- Default: `'button'`
+
+CSS class for `<button>` elements. (view switch, prev/next buttons, clear and today buttons)
+
+> For constructor only. Cannot be used with `setOptions()`.  
+
+#### calendarWeeks
+- Type: `Boolean`
+- Default: `false`
+
+Whether to show the week number ([ISO week](https://en.wikipedia.org/wiki/ISO_week_date)) on week rows.
+
+#### clearBtn
+- Type: `Boolean`
+- Default: `false`
+
+Whether to show the clear button.
+
+#### container
+- Type: `String`
+- Default: `body`
+
+CSS selector for the element to append the date picker.
+
+> For constructor only. Cannot be used with `setOptions()`.  
+> On inline picker, this option is ignored and overwritten to the associated element.
+
+#### dateDelimiter
+- Type: `String`
+- Default: `','`
+
+Delimiter string to separate the dates in a multi-date string.
+
+> The delimiter must not be included in date format string.
+
+#### datesDisabled
+- Type: `Array`
+- Default: `[]`
+
+Dates to disable. Array of date strings, Date objects, time values or mix of those.
+
+> Multi-date string cannot be used. Use multiple single-date strings instead.
+
+#### daysOfWeekDisabled
+- Type: `Number[]`
+- Default: `[]`
+
+Days of the week to disable. `0`:_Sunday_ – `6`:_Saturday_, up to 6 items.
+
+#### daysOfWeekHighlighted
+- Type: `Number[]`
+- Default: `[]`
+
+Days of the week to highlight. `0`:_Sunday_ – `6`:_Saturday_, up to 6 items.
+
+#### defaultViewDate
+- Type: `String`|`Date`|`Number`
+- Default: current date
+
+The date to be focused when the date picker opens with no selected date(s).
+
+#### disableTouchKeyboard
+- Type: `Boolean`
+- Default: `false`
+
+Whether to prevent on-screen keyboard on mobile devices from showing up when the associated input field receives focus.
+
+> Not available on inline picker.
+
+#### format
+- Type: `String`|`Object`
+- Default: `'mm/dd/yyyy'`
+
+[Date format](date-string+format?id=date-format) string.
+
+> The format string must not include the [dateDelimiter](options?id=datedelimiter) string.
+
+Alternatively, object that contains custom parser and formatter functions can be used.
+
+- **Parser**
+  - Property \(function\) name: `toValue`
+  - Arguments:
+    - `date`: {`String`|`Date`|`Number`} - date string, Date object or time value to parse
+    - `format`: {`Object`} - format object itself
+    - `locale`: {`Object`} - locale of the current language
+  - Return:
+    - {`Date`} - parsed date object
+- **Formatter**
+  - Property \(function\) name: `toDisplay`
+  - Arguments::
+    - `date`: {`Date`} - date object to format
+    - `format`: {`Object`} - format object itself
+    - `locale`: {`Object`} - locale of the current language
+  - Return:
+    - {`String`} - formated date
+
+```javascript
+{
+    format: {
+        toValue(date, format, locale) {
+            let dateObject;
+            //...your custom parse logic
+            return dateObject;
+        },
+        toDisplay(date, format, locale) {
+            let dateString;
+            //...your custom format logic
+            return dateString;
+        },
+    },
+}
+```
+
+#### language
+- Type: `String`
+- Default: `'en'`
+
+The language code of the language used by the date picker.
+
+> For languages other than `en` to work, their locales must be loaded into your project/program.  
+> See [i18n](i18n) for the details.
+
+#### maxDate
+- Type: `String`|`Date`|`Number`
+- Default: `null`
+
+Maximum limit to selectable date. No limit is applied if `null` is set.
+
+#### maxNumberOfDates
+- Type: `Number`
+- Default: `1`
+
+Maximum number of dates users can select. No limit is applied if `0` is set.
+
+> Not available for date range picker.
+
+#### maxView
+- Type: Number
+- Default: `3`
+
+Maximum limit to the view that the date picker displays. `0`:_days_ – `3`:_decades_.
+
+#### minDate
+- Type: `String`|`Date`|`Number`
+- Default: `null`
+
+Minimum limit to selectable date. No limit is applied if `null` is set.
+
+#### nextArrow
+- Type: `String`
+- Default: `'»'`
+
+HTML (or plain text) for the button label of the "Next" button.
+
+> See the note in [i18n ≻ Text Direction](i18n?id=text-direction) when using with RTL languages.
+
+#### orientation
+- Type: `String`
+- Default: `'auto'`
+
+Space-separated string for date picker's horizontal and vertical placement to the associated input field. `left`|`right`|`auto` for horizontal and `top`|`bottom`|`auto` for vertical.
+
+> The order can be random.  
+> If one direction is omitted, it falls back to `auto`. (e.g. `'top'` == `'top auto'`)  
+> Not available on inline picker.
+
+#### pickLevel
+- Type: `Number`
+- Default: `0`
+
+The level that the date picker allows to pick. `0`:_date_,`1`: _month_ &nbsp;or `2`:_year_.
+
+> When this option is `1`, the selected date becomes the 1st of the month or, if the date picker is the end-date picker of date range picker, the last day of the month.  
+> When this option is `2`, the selected date becomes January 1st of the year or, if the date picker is the end-date picker of date range picker, December 31st of the year.
+
+#### prevArrow
+- Type: `String`
+- Default: `'«'`
+
+HTML (or plain text) for the button label of the "Prev" button.
+
+> See the note in [i18n ≻ Text Direction](i18n?id=text-direction) when using with RTL languages.
+
+#### showDaysOfWeek
+- Type: `Boolean`
+- Default: `true`
+
+Whether to show the day names of the week.
+
+#### showOnClick
+- Type: `Boolean`
+- Default: `true`
+
+Whether to show the date picker when the associated input filed is clicked.
+
+> Not available on inline picker.
+
+#### showOnFocus
+- Type: `Boolean`
+- Default: `true`
+
+Whether to show the date picker automatically when the associated input filed receives focus.
+
+> Not available on inline picker.
+
+#### startView
+- Type: `Number`
+- Default: `0`
+
+The view displayed when the date picker opens. `0`:_days_ – `3`:_decades_.
+
+#### title
+- Type: `String`
+- Default: `''`
+
+Title string shown in the date picker's title bar.
+
+> The title bar is not displayed if the title is empty.
+
+#### todayBtn
+- Type: `Boolean`
+- Default: `false`
+
+Whether to show the today button.
+
+#### todayBtnMode
+- Type: `Number`
+- Default: `0`
+
+The mode how the today button behaves.
+
+Mode | Name | Description
+--|--|--
+`0` | focus | Move the focused date to the current date without changing the selection  
+`1` | select | Select (or toggle the selection of) the current date
+
+#### todayHighlight
+- Type: `Boolean`
+- Default: `false`
+
+Whether to highlight the current date.
+
+#### updateOnBlur
+- Type: `Boolean`
+- Default: `true`
+
+Whether to update the selected date(s) with the input field's value when the input field is losing focus.
+
+> When this option is `false`, if the user edits the date string in input field, it will be parsed and applied only when the user presses the <kbd>Enter</kbd> key. If the edit is left unparsed, it will be discarded when input field becomes unfocused (by <kbd>Tab</kbd> key press or click outside the picker element/input field).
+>
+> Not available on inline picker.
+
+#### weekStart
+- Type: `Number`
+- Default: `0`
+
+Start day of the week. `0`:_Sunday_ – `6`:_Saturday_.
+
+
+### DateRangePicker Options
+
+#### allowOneSidedRange
+- Type: `Boolean`
+- Default: `false`
+
+Whether to allow one side of the date-range to be blank.
+
+> When this option is `false`, if the user selects a date on one side while the other side is blank, the date range picker complements the blank side with the same date as the selected side.  
+> Similarly, if the user clears one side of the date-range, the date range picker also clears the other side automatically.
+
+#### inputs
+- Type: `Element[]`
+- Default: `input` elements inside the associated block element
+
+Input fields to attach start- and end-date pickers. Must contain 2 items.
+
+> For constructor only. Cannot be used with `setOptions()`.

package/docs/overview.md

@@ -0,0 +1,174 @@
+# Overview
+
+## Types
+
+##### Date picker (regular/text-input picker)
+
+When Datepicker object is attached to an `<input>` element, it's configured as a regular date picker.
+
+![](./images/datepicker.jpg)
+
+##### Inline picker
+
+When Datepicker object is attached to a block element, it's configured as an inline picker.
+
+![](./images/datepicker-inline.jpg)
+
+- The picker element is embedded to the block element. (always shown)
+- Initial selection can be set in the `data-date` attribute
+- Inline picker does not support operation by keyboard.
+
+##### Date range picker
+
+Date range picker is essentially a wrapper/controller of 2 date pickers. It's the only type of DateRangePicker object.
+
+![](./images/rangepicker.jpg)
+
+- Date range picker cannot be attached to elements that contain less than 2 `<input>` elements
+- Regular date picker is attached to each of `<input>` elements
+
+
+## Picker Element
+
+![](./images/picker-structure.jpg)
+
+1. **Title bar**
+2. **View switch**:  
+   Button to change the view from days to months, months to years and years to decades  
+   The button label is used for the title of view contents.
+3. **Prev button**:  
+   Button to change the contents of the current view to the previous month/year/decade/century
+4. **Next button**:  
+   Button to change the contents of the current view to the next month/year/decade/century
+5. **View**:  
+   Area to display a calendar (for days) or a grid of months, years, or decades
+6. **Cell**:  
+   Block for each day, month, year or decade  
+   It works as a select button in days view. In the other views, it works as a button to change the view to the period of time it represents. (months view → days view of the month, years → months of the year, decades → years of the decade) 
+7. **Today button**:  
+   Button to jump to the current date  
+   It can be customized to select the current date.
+8. **Clear button**:  
+   Button to clear the selection
+
+##### Days view
+
+The view to select a date. The days are displayed in monthly calendar layout. Optionally, ISO week numbers can be shown in the view.
+
+![](./images/view-days.jpg)
+
+##### Months view
+
+The view to select a month. The months are shown in short name.
+
+![](./images/view-months.jpg)
+
+##### Years view
+
+The view to select a year.
+
+![](./images/view-years.jpg)
+
+##### Decades view
+
+The view to select a decade.
+
+![](./images/view-decades.jpg)
+
+
+## Multidate Mode
+
+When [`maxNumberOfDates`](options?id=maxnumberofdates) config option is set to other than `1`, date picker turns to the multdate mode.
+
+In this mode, the day cells in the days view act as toggle switch of the date's select status. The order of selection is kept; newly selected date is appended to the existing selection and the oldest item in the selection drops if the number of selected dates exceeds the option's value.  
+In the input field, selected dates are joined with the delimiter string set in the [`dateDelimiter`](options?id=dateDelimiter) config option.
+
+![](./images/multidate.jpg)
+
+Multidate mode is not applied to the pickers of date range picker.
+
+## Providing date
+
+Datepicker accepts [date string](date-string+format), Date object or [time value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#Time_value_or_timestamp_number) for the source of a date. All given dates are parsed/converted into the internal date value individually.
+
+> The time value of local time `00:00:00.000` of the date is used for the internal date value.
+
+The dates before _January 1st, 0000_ are not supported because the built-in parser cannot handle negative numbers. (`-` sign is one of the predefined separator characters)
+
+To provide dates for config options or API method arguments, you can just follow the above general rules.
+
+##### Initial selection
+
+To provide initial date selection to a date picker, you can set a date string to the `<input>` element's `value` attribute. This also works for date range picker's `<input>` elements.
+
+For inline picker, you can set a date string to the `data-date` attribute of the element to attach the picker.
+
+##### Input field
+
+You can update the selected date by editing the date string in the input field.
+
+> Since the built-in parser is very tolerant of format errors, a small typing error can cause an unexpected (and sometimes unimaginable) date in the input field. _(See [How Built-in Parser parses](./date-string+format?id=how-built-in-parser-parses))_  
+> If you think this is not good, you might want to consider using the [`updateOnBlur`](./options?id=updateonblur):`false` config option in order to implicitly nudge users to look at their input.
+
+## Keyboard Operation
+
+You can operate date picker using keyboard. Here are the available keyboard operations.
+
+**When picker is hidden**
+
+- <KBD>**↓**</KBD> (arrowDown)**,** <kbd>**Esc**</kbd> **:**  
+  Show the picker
+- <kbd>**Enter**</kbd> **:**  
+  Update the picker with the input field's value
+
+**When picker is shown**
+
+- <kbd>**Esc**</kbd> **:**  
+  Hide the picker
+- <kbd>**←**</kbd> (arrowLeft)**,** <kbd>**→**</kbd> (arrowRight) **:**  
+  Move focused date/month/year/decade 1 step horizontally
+- <kbd>**↑**</kbd> (arrowUp)**,** <kbd>**↓**</kbd> (arrowDown) **:**  
+  Move focused date/month/year/decade 1 step vertically
+- <kbd>**Ctrl**</kbd> (or <kbd>Meta</kbd>) **+** <kbd>**←**</kbd> (arrowLeft) **:**  
+  Move to previous month/year/decade/century _(Shortcut of the "Prev" button)_
+- <kbd>**Ctrl**</kbd> (or <kbd>Meta</kbd>) **+** <kbd>**→**</kbd> (arrowRight) **:**  
+  Move to next month/year/decade/century _(Shortcut of the "Next" button)_
+- <kbd>**Ctrl**</kbd> (or <kbd>Meta</kbd>) **+** <kbd>**↑**</kbd> (arrowUp) **:**    
+  Change the view upward _(Shortcut of the view switch)_
+- <kbd>**Enter**</kbd> **:**
+  - *when days view is shown:*  
+    Select the focused date 
+  - *otherwise:*  
+    Change the view downward for the focused decade/year/month 
+- <kbd>**Backspace**</kbd>**,** <kbd>**Delete**</kbd>**, any printable character,** <kbd>**Shift**</kbd> **+ either of arrow keys** ( <kbd>←</kbd>/<kbd>→</kbd>/<kbd>↑</kbd>/<kbd>↓</kbd> ) **:**  
+  Enter [edit mode](overview?id=edit-mode)
+
+**When in [edit mode](overview?id=edit-mode)**
+
+- <kbd>**Esc**</kbd> **:**  
+  Hide the picker exiting edit mode
+- <kbd>**Enter**</kbd> **:**   
+  Exit edit mode updating the picker with the change on the input field
+
+> Note: Keyboard operation is not supported by inline picker.
+
+## Edit Mode 
+
+When the picker element is shown, date picker (in the primary state) captures key-press events and uses them to control the picker element. Therefore, users cannot edit the `<input>` element in this state.  
+To solve this, Datepicker has the edit mode.
+
+Date picker automatically enters edit mode when:
+
+- the `<input>` element is clicked
+- <kbd>Backspace</kbd>, <kbd>Delete</kbd> or any of printable character key is pressed (without control/meta key).
+- <kbd>Shift</kbd> + either of arrow keys ( <kbd>←</kbd>/<kbd>→</kbd>/<kbd>↑</kbd>/<kbd>↓</kbd> ) is pressed (without control/meta key).
+
+and exits edit mode when:
+
+- <kbd>Enter</kbd> key or <kbd>Esc</kbd> key is pressed
+- the picker element becomes hidden
+
+While date picker is in edit mode,
+
+- highlight of the `<input>` element becomes more prominent
+- keyboard operation of the picker element is temporarily disabled