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

package/docs/README.md

@@ -0,0 +1,266 @@
+# Vanilla JS Datepicker
+
+A vanilla JavaScript remake of [bootstrap-datepicker](https://github.com/uxsolutions/bootstrap-datepicker) for [Bulma](https://bulma.io) and other CSS frameworks  
+
+This package is written from scratch as ECMAScript modules/[Sass](https://sass-lang.com) stylesheets to reproduce similar usability to bootstrap-datepicker.  
+It can work either standalone or with CSS framework (e.g. [Bootstrap](https://getbootstrap.com), [Foundation](https://get.foundation)), but works best with [Bulma](https://bulma.io) as it's developed primarily for Bulma. 
+
+The package also includes pre-built js/css files for those who like to use it directly on browser.
+
+##### Features
+
+- Date picker (input-dropdown, inline), date range picker
+- Keyboard operation support (navigation by arrow keys, editing on input field)
+- i18n support (locales, CSS-based text direction detection)
+- Easily customizable to adapt stylesheet for various CSS frameworks
+- Dependency free
+- Made for modern browsers — no IE support
+- Lightweight (well, relatively…) — 33kB (minified, uncompressed)
+
+##### Demo
+
+[Live Online Demo](https://raw.githack.com/mymth/vanillajs-datepicker/v1.1.4/demo/)
+
+## Quick Start
+
+Install the package using npm.
+
+```bash
+npm install --save-dev vanillajs-datepicker 
+```
+
+##### Date picker
+
+– **Input picker**
+
+1. create a text input element.
+
+```html
+<input type="text" name="foo">
+```
+
+2. import the `Datepicker` module.
+
+```javascript
+import Datepicker from 'path/to/node_modules/vanillajs-datepicker/js/Datepicker.js';
+```
+
+_Or if you use a bundler that supports [pkg.module](https://github.com/rollup/rollup/wiki/pkg.module) (e.g. [Rollup](https://rollupjs.org/) with [node-resolve](https://github.com/rollup/plugins/tree/master/packages/node-resolve) plugin, [webpack](https://webpack.js.org/))_
+
+```javascript
+import { Datepicker } from 'vanillajs-datepicker';
+```
+
+_Or if your bundler supports [package entry points](https://nodejs.org/api/packages.html#packages_package_entry_points) (e.g. Rollup with node-resolve plugin v8.4+, webpack v5+), you can also do this._
+
+```javascript
+import Datepicker from 'vanillajs-datepicker/Datepicker';
+```
+
+3. call `Datepicker` constructor with the input element and, optionally, [config options](options).
+
+```javascript
+const elem = document.querySelector('input[name="foo"]');
+const datepicker = new Datepicker(elem, {
+  // ...options
+}); 
+```
+
+![](./images/datepicker.jpg)
+
+
+– **Inline picker**
+
+1. create a block element.
+
+```html
+<div id="foo" data-date="01/25/2020"></div>
+```
+
+2. import the `Datepicker` module in the same way as Input picker.
+
+
+3. call `Datepicker` constructor with the block element and, optionally, [config options](options).
+
+```javascript
+const elem = document.getElementById('foo');
+const datepicker = new Datepicker(elem, {
+  // ...options
+}); 
+```
+
+![](./images/datepicker-inline.jpg)
+
+
+##### Date range picker
+
+1. create a block element that contains 2 text input elements.
+
+```html
+<div id="foo">
+  <input type="text" name="start">
+  <span>to</span>
+  <input type="text" name="end">  
+</div>
+```
+
+2. import the `DateRangePicker` module.
+
+```javascript
+import DateRangePicker from 'path/to/node_modules/vanillajs-datepicker/js/DateRangePicker.js';
+```
+
+_Or if you use a bundler that supports [pkg.module](https://github.com/rollup/rollup/wiki/pkg.module) (e.g. [Rollup](https://rollupjs.org/) with [node-resolve](https://github.com/rollup/plugins/tree/master/packages/node-resolve) plugin, [webpack](https://webpack.js.org/))_
+
+```javascript
+import { DateRangePicker } from 'vanillajs-datepicker';
+```
+
+_Or if your bundler supports [package entry points](https://nodejs.org/api/packages.html#packages_package_entry_points) (e.g. Rollup with node-resolve plugin v8.4+, webpack v5+), you can also do this._
+
+```javascript
+import DateRangePicker from 'vanillajs-datepicker/DateRangePicker';
+```
+
+3. call `DateRangePicker` constructor with the block element and, optionally, [config options](options).
+
+```javascript
+const elem = document.getElementById('foo');
+const rangepicker = new DateRangePicker(elem, {
+  // ...options
+}); 
+```
+
+![](./images/rangepicker.jpg)
+
+##### Stylesheet
+
+1. import scss file.
+
+```scss
+@import 'path/to/node_modules/vanillajs-datepicker/sass/datepicker';
+```
+
+### Using with CSS framework
+
+#### Bulma
+
+1. import scss file for Bulma instead.
+
+```scss
+@import 'path/to/node_modules/vanillajs-datepicker/sass/datepicker-bulma';
+```
+
+#### Bootstrap
+
+1. use `buttonClass: 'btn'` option to call `Datepicker`/`DateRangePicker` constructor.
+
+```javascript
+const datepicker = new Datepicker(elem, {
+  buttonClass: 'btn',
+}); 
+```
+
+2. import scss file for Bootstrap instead.
+
+```scss
+@import 'path/to/node_modules/vanillajs-datepicker/sass/datepicker-bs4';
+```
+
+#### Foundation
+
+1. import scss file for Foundation instead.
+
+```scss
+@import 'path/to/node_modules/vanillajs-datepicker/sass/datepicker-foundation';
+```
+
+#### Other frameworks
+
+ 1. If the framework uses a specific class for button elements, set it to the `buttonClass` option to call `Datepicker`/`DateRangePicker` constructor.
+
+```javascript
+const datepicker = new Datepicker(elem, {
+  buttonClass: 'uk-button',
+}); 
+```
+
+2. Copy the following template into your sass stylesheet, and edit the node_module path, the variables, button class and button style adjustments to match your environment.
+
+```scss
+/***
+ Copy the datepicker variables (the ones with `dp-` prefix and `!default` flag)
+ from `sass/Datepicker.scss` to here
+ Then, edit them using your framework's variables/values
+ e.g.:
+ $dp-background-color: $background !default;
+ $dp-border-color: $border !default;
+ ...
+ ***/
+
+@import '../node_modules/vanillajs-datepicker/sass/mixins';
+
+@mixin dp-button {
+  .button {
+    /***
+     Place style adjustment for date picker's buttons here, if needed
+     ***/
+
+    .datepicker-header & {
+      @include dp-header-button-common;
+
+      /***
+       Place style adjustment specific to the header buttons here, if needed
+       ***/
+    }
+
+    .datepicker-footer & {
+      @include dp-footer-button-common;
+
+      /***
+       Place style adjustment specific to the footer buttons here, if needed
+       ***/
+    }
+  }
+}
+
+@import '../node_modules/vanillajs-datepicker/sass/datepicker';
+```
+
+### Using from Browser
+
+1. From CDN, load css and js files.
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/css/datepicker.min.css">
+
+...
+
+<script src="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/js/datepicker-full.min.js"></script>
+```
+
+_If you use Bulma, Bootstrap or Foundation, you can use the css for your framework instead._
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/css/datepicker-bulma.min.css">
+<!-- or -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/css/datepicker-bs4.min.css">
+<!-- or -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/css/datepicker-foundation.min.css">
+```
+
+_And if don't need date range, you can use the datepicker-only version of js file._
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/vanillajs-datepicker@1.1.4/dist/js/datepicker.min.js"></script>
+```
+
+2. Call `Datepicker`/`DateRangePicker` constructor in the same way as explained [above](?id=quick-start). (The classes are exposed to global scope.)
+
+```javascript
+const elem = document.querySelector('input[name="foo"]');
+const datepicker = new Datepicker(elem, {
+  // ...options
+}); 
+```
+

package/docs/_sidebar.md

@@ -0,0 +1,6 @@
+* [Home](/)
+* [Overview](overview.md)
+* [Options](options.md)
+* [API](api.md)
+* [Date String & Format](date-string+format.md)
+* [i18n](i18n.md)

package/docs/api.md

@@ -0,0 +1,284 @@
+# API
+
+## Datepicker
+
+### Static Properties
+
+#### Datepicker.locales
+- Type: `Object`
+
+Installed locales in `[languageCode]: localeObject` format. `en`:_English (US)_ is pre-installed.
+
+> See [i18n](i18n) for the details.
+
+### Static Methods
+
+#### Datepicker.formatDate()
+
+Format a Date object or a time value using given format and language
+
+```javascript
+Datepicker.formatDate( date , format [, lang ] )
+```
+- **Arguments:**
+  - `date`: {`Date`|`Number`} - Date or time value to format
+  - `format`: {`String`|`Object`} - Format string or object that contains `toDisplay()` custom formatter  
+    See [Options ≻ format](options?id=format)
+  - [`lang`] : {`String`} - Language code for the locale to use  
+    – Default: `'en'`
+- **Return:**
+  - {`String`} - Formatted date
+
+#### Datepicker.parseDate()
+
+Parse date string (or Date/time value) using given format and language
+
+```javascript
+Datepicker.parseDate( dateStr , format [, lang ] )
+```
+- **Arguments:**
+  - `dateStr`: {`String`|`Date`|`Number`} - Date string, Date object or time value to parse
+  - `format`: {`String`|`Object`} - Format string or object that contains `toValue()` custom parser  
+    See [Options ≻ format](options?id=format)
+  - [`lang`] : {`String`} - Language code for the locale to use  
+    – Default: `'en'`
+- **Return:**
+  - {`Number`} - Time value of parsed date
+
+
+### Instance Properties
+
+#### datepicker.active
+- Type: `Boolean`
+
+Whether the picker element is shown  
+(Read-only)
+
+#### datepicker.pickerElement
+- Type: `HTMLDivElement`
+
+DOM object of picker element  
+(Read-only)
+
+#### datepicker.rangepicker
+- Type: `DateRangePicker`
+
+DateRangePicker instance that the datepicker belongs to  
+Only avalable when the datepicker is a part of date range picker  
+(Read-only)
+
+
+### Instance Methods
+
+#### datepicker.destroy()
+
+Destroy the Datepicker instance
+
+```javascript
+datepicker.destroy()
+```
+- **Return:**
+  - {`Detepicker`} - The instance destroyed
+
+#### datepicker.getDate()
+
+Get selected date(s)
+
+The method returns a Date object of selected date by default, and returns an array of selected dates in multidate mode. If format string is passed, it returns date string(s) formatted in given format.
+
+```javascript
+datepicker.getDate( [ format ] )
+```
+- **Arguments:**
+  - [`format`] : {`String`} - Format string to stringify the date(s)
+- **Return:**
+  - {`Date`|`String`} - Selected date (or `undefined` if none is selected)
+  - {`Date[]`|`String[]`} - Array of selected dates (or empty array if none is selected)
+
+#### datepicker.hide()
+
+Hide the picker element  
+Not available on inline picker
+
+```javascript
+datepicker.hide()
+```
+
+#### datepicker.refresh()
+
+Refresh the picker element and the associated input field
+
+```javascript
+datepicker.refresh( [ target ], [ forceRender ] )
+```
+- **Arguments:**
+  - [`target`] : {`String`} - Target item when refreshing one item only. `'picker'` or `'input'`
+  - [`forceRender`] : {`Boolean`} - Whether to re-render the picker element regardless of its state instead of optimized refresh  
+    – Default: `'false'`
+
+#### datepicker.setDate()
+
+Set selected date(s)
+
+In multidate mode, you can pass multiple dates as a series of arguments or an array. (Since each date is parsed individually, the type of the dates doesn't have to be the same.)  
+The given dates are used to toggle the select status of each date. The number of selected dates is kept from exceeding the length set to `maxNumberOfDates`. See [Multidate Mode](overview?id=multidate-mode) for more details.
+
+With `clear: true` option, the method can be used to clear the selection and to replace the selection instead of toggling in multidate mode. If the option is passed with no date arguments or an empty dates array, it works as "clear" (clear the selection then set nothing), and if the option is passed with new dates to select, it works as "replace" (clear the selection then set the given dates)
+
+When `render: false` option is used, the method omits re-rendering the picker element. In this case, you need to call [`refresh()`](api?id=datepickerrefresh) method later in order for the picker element to reflect the changes. The input field is refreshed always regardless of this option.
+
+When invalid (unparsable, repeated, disabled or out-of-range) dates are passed, the method ignores them and applies only valid ones. In the case that all the given dates are invalid, which is distinguished from passing no dates, the method considers it as an error and leaves the selection untouched.
+
+```javascript
+datepicker.setDate( date1 [, date2 [, ... dateN ]][, options ] )
+datepicker.setDate( dates [, options ] )
+datepicker.setDate( [ options ] )
+```
+- **Arguments:**
+  - [`...dates`] : {...(`String`|`Date`|`Number`)|`Array`} - Date strings, Date objects, time values or mix of those for new selection
+  - [`options`] : {`Object`} - Function options:
+    - `clear`: {`Boolean`} - Whether to clear the existing selection  
+      – Default: `false`
+    - `render`: {`Boolean`} - Whether to re-render the picker element  
+      – Default: `true`
+    - `autohide`: {`Boolean`} - Whether to hide the picker element after re-render  
+      Ignored when used with `render: false`  
+      – Default: the value of `autohide` config option
+
+#### datepicker.setOptions()
+
+Set new values to the config options
+
+```javascript
+datepicker.setOptions( options )
+```
+- **Arguments:**
+  - `options`: {`Object`} - Config options to update
+
+#### datepicker.show()
+
+Show the picker element
+
+```javascript
+datepicker.show()
+```
+
+#### datepicker.update()
+
+Update the selected date(s) with input field's value  
+Not available on inline picker
+
+The input field will be refreshed with properly formatted date string.
+
+```javascript
+datepicker.update( [ options ] )
+```
+- **Arguments:**
+  - [`options`] : {`Object`} - Function options:
+    - `autohide`: {`Boolean`} - Whether to hide the picker element after update  
+       – Default: `false`
+
+
+### Events
+
+All Datepicker-event objects are `CustomEvent` instances and dispatched to the associated `<input>` element (for inline picker, the block element).  
+They include the following extra data in the `detail` property.
+
+- `date`: {`Date`} - Selected date(s) (see [getDate()](api?id=datepickergetdate))
+- `viewDate`: {`Date`} - Focused date
+- `viewId`: {`Number`} - ID of the current view
+- `datepicker`: {`Datepicker`} - Datepicker instance
+
+#### changeDate
+
+Fired when the selected dates are changed.
+
+#### changeMonth
+
+Fired when the focused date is changed to a different month's date. 
+
+#### changeView
+
+Fired when the current view is changed.
+
+#### changeYear
+
+Fired when the focused date is changed to a different year's date. 
+
+#### hide
+
+Fired when the date picker becomes hidden.
+
+#### show
+
+Fired when the date picker becomes visible.
+
+
+## DateRangePicker
+
+### Instance Properties
+
+#### rangepicker.datepickers
+- Type: `Array`
+
+Array of associated Datepicker instances  
+(Read-only)
+
+
+### Instance Methods
+
+#### rangepicker.destroy()
+
+Destroy the DateRangePicker instance
+
+```javascript
+rangepicker.destroy()
+```
+- **Return:**
+  - {`DateRangePicker`} - The instance destroyed
+
+#### rangepicker.getDates()
+
+Get the start and end dates of the date-range
+
+The method returns Date objects by default. If format string is passed, it returns date strings formatted in given format.  
+The result array always contains 2 items (start date/end date) and `undefined` is used for unselected side. (e.g. If none is selected, the result will be `[undefined, undefined]`. If only the end date is set when `allowOneSidedRange` config option is `true`, `[undefined, endDate]` will be returned.)
+
+```javascript
+rangepicker.getDates( [ format ] )
+```
+- **Arguments:**
+  - [`format`] : {`String`} - Format string to stringify the dates
+- **Return:**
+  - {`Date[]`|`String[]`} - Start and end dates
+
+#### rangepicker.setDates()
+
+Set the start and end dates of the date range
+
+The method calls [`datepicker.setDate()`](api?id=datepickersetdate) internally using each of the arguments in start→end order.
+
+When a `clear: true` option object is passed instead of a date, the method clears the date.
+
+If an invalid date, the same date as the current one or an option object without `clear: true` is passed, the method considers that argument as an "ineffective" argument because calling [`datepicker.setDate()`](api?id=datepickersetdate) with those values makes no changes to the date selection.
+
+When the [`allowOneSidedRange`](options?id=allowonesidedrange) config option is `false`, passing `{clear: true}` to clear the range works only when it is done to the last effective argument (in other words, passed to `rangeEnd` or to `rangeStart` along with ineffective `rangeEnd`). This is because when the date range is changed, it gets normalized based on the last change at the end of the changing process.
+
+```javascript
+rangepicker.setDates( rangeStart , rangeEnd )
+```
+- **Arguments:**
+  - `rangeStart` : {`Date`|`Number`|`String)`|`Object`} - Start date of the range or `{clear: true}` to clear the date
+  - `rangeEnd` : {`Date`|`Number`|`String)`|`Object`} - End date of the range or `{clear: true}` to clear the date
+
+#### rangepicker.setOptions()
+
+Set new values to the config options
+
+```javascript
+rangepicker.setOptions( options )
+```
+- **Arguments:**
+  - `options`: {`Object`} - Config options to update
+
+

package/docs/date-string+format.md

@@ -0,0 +1,90 @@
+# Date String & Format
+
+## Date format
+
+Date format must be declared using the combination of the predefined tokens and separators.
+
+**– Tokens:**
+
+Token | Description | Example
+--|--|--
+`d` | day of the month without leading zero | 1, 2, ..., 31
+`dd` |  day of the month with leading zero | 01, 02, ..., 31
+`D` | shortened day name of the week | Sum, Mon, ..., Sat
+`DD` | full day name of the week | Sunday, Monday, ..., Saturday
+`m` | numeric month without leading zero | 1, 2, ..., 12
+`mm` | numeric month with leading zero | 01, 02, ..., 12
+`M` | shortened month name | Jan, Feb, ..., Dec
+`MM` | full month name | January, February, ..., December
+`y` | year without leading zero | 1, 645, 1900, 2020
+`yy` | 2-digit year with leading zero | 01, 45, 00, 20
+`yyyy` | 4-digit year with leading zero | 0001, 0645, 1900, 2020
+
+**– Separators:**
+
+All printable ASCII characters other than numbers and alphabets, `年`, `月` and `日`
+
+**Notes**
+
+- Since the built-in parser extracts the parts of the date by splitting the string with the separators, formats without separators (e.g. `yyyymmdd`) are not supported.
+- 2-digit year (`yy`) is only supported by the built-in formatter; the built-in parser doesn't.
+
+> You can write your custom parser/formatter to handle arbitrary format including the above. See [`format` config option](options?id=format) for the details.
+
+- Date format must not include the string set in the [`dateDelimiter`](options?id=datedelimiter) config option.
+
+## Date string
+
+Date strings are expected to be formatted in the date format set in the [`format`](options?id=format) config option (default: `mm/dd/yyyy`), but it isn't necessary to match the format strictly.
+
+##### How Built-in Parser parses
+
+The built-in parser uses the format string only to determine the sequence in which the date parts (year/month/day/day-of-the-week) and separators appear in the date string. The differences in separator characters, whether to have leading zeros and whether month name (full or short) or month number is used are ignored. Therefore, as long as the parts of a date string appear in the same order as the format's, the variations of the same date's date string are equally parsed to the same date. 
+
+There are some cases the parser treats the parts in specific way:
+- year is treated as full year _(1-/2-digit years are not mapped to nearby century's)_
+- month number not between 1 and 12 is treated in the similar way to [`Date.prototype.setMonth()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setMonth)
+- month name is evaluated in case-insensitive begin-with match
+- day not between 1 and last-day-of-the-month is treated in the same way as [`Date.prototype.setDate()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/setDate)
+- day-of-the-week is not evaluated _(not totally ignored, the existence is respected)_
+- if a part is omitted from the format, missing in the date string or parsed unsuccessfully, current date's value is used to complement.
+
+Here are some examples of how irregular date strings are parsed.
+
+- Different separators from the format:  
+  - if format is `yyyy-mm-dd`, `2020/04/22` ⟹ _April 22nd, 2020_
+  - if format is `m.d.y`, `1/15 (2018)` ⟹ _January 15th, 2018_
+- With/without leading zeros:  
+  - if format is `d/m/y`, `05/06/07` ⟹ _June 5th, 0007_
+  - if format is `yyyy-mm-dd`, `20-5-4` ⟹ _May 4th, 0020_
+- Number for the month name:  
+  - if format is `M-d-y`, `7-14-2020` ⟹ _July 14th, 2020_
+- Incomplete month name/full name for short name:  
+  - if format is `M-d-y`,
+    - `ap-22-2020` ⟹ _April 22nd, 2020_
+    - `sept-22-2020` ⟹ _September 22nd, 2020_
+    - `Ju-4-2020` ⟹ _June 4th, 2020_
+    - `July-4-2020` ⟹ _July 4th, 2020_
+- Month/day outside the normal range:  
+  - if format is `mm/dd/yyyy`,
+    - `14/31/2019` ⟹ _March 2nd, 2020_
+    - `0/0/2020` ⟹ _November 30th, 2019_
+- Omitted/missing/invalid parts:  
+  - if format is `mm/yyyy` and current date is _January 15th, 2020_,
+    - `04/2022` ⟹ _April 15th, 2022_
+  - if format is `m/d/y` and current date is _January 15th, 2020_,
+    - `4/22` ⟹ _April 22nd, 2020_
+    - `/22/2016` ⟹ _January 22nd, 2016_
+    - `7/xx/2016` ⟹ _July 15th, 2016_
+- Day-of-the-week:
+  - if format is `D m/d y` and current date is _January 15th, 2020_,
+    - `xx 5/4 2022` ⟹ _May 4th, 2022_
+    - `5/4 2022` ⟹ _October 13th, 2025 (= April 2022nd, 2020)_
+
+##### 'Today' shortcut
+
+You can use `'today'` as a shortcut to the current date.
+
+##### Multiple dates
+
+You can combine multiple dates into a single date string by joining the dates with the delimiter set in the [dateDelimiter](options?id=datedelimiter) config option.