1 | <div align="center" style="text-align: center;">
|
2 | <h1 style="border-bottom: none;">app-datepicker</h1>
|
3 |
|
4 | <p>Datepicker element built with lit and Material Design 2021</p>
|
5 | </div>
|
6 |
|
7 | <hr />
|
8 |
|
9 | [![buymeacoffee][buymeacoffee-badge]][buymeacoffee-url]
|
10 | [![tippin.me][tippin-me-badge]][tippin-me-url]
|
11 | [![Follow me][follow-me-badge]][follow-me-url]
|
12 | [![Join Discord][join-discord-badge]][join-discord-url]
|
13 |
|
14 | [![Version][version-badge]][version-url]
|
15 | [![lit][lit-version-badge]][lit]
|
16 | [![MIT License][mit-license-badge]][mit-license-url]
|
17 |
|
18 | [![Downloads][downloads-badge]][downloads-url]
|
19 | [![Total downloads][total-downloads-badge]][downloads-url]
|
20 | [![Packagephobia][packagephobia-badge]][packagephobia-url]
|
21 | [![Bundlephobia][bundlephobia-badge]][bundlephobia-url]
|
22 |
|
23 | [![ci][ga-ci-badge]][ga-ci-url]
|
24 | [![ci-helpers][ga-ci-helpers-badge]][ga-ci-helpers-url]
|
25 | [![codecov][codecov-badge]][codecov-url]
|
26 |
|
27 | [![Code of Conduct][coc-badge]][coc-url]
|
28 |
|
29 | ## Table of contents <!-- omit in toc -->
|
30 |
|
31 | - [Pre-requisite](#pre-requisite)
|
32 | - [Installation](#installation)
|
33 | - [How to use](#how-to-use)
|
34 | - [Polyfills](#polyfills)
|
35 | - [ES Modules](#es-modules)
|
36 | - [my-app.js](#my-appjs)
|
37 | - [index.html](#indexhtml)
|
38 | - [Browser compatibility](#browser-compatibility)
|
39 | - [Q&A](#qa)
|
40 | - [API references](#api-references)
|
41 | - [Demo](#demo)
|
42 | - [Older versions](#older-versions)
|
43 | - [License](#license)
|
44 |
|
45 | > Miracle happens when marrying Material Design with date pickers on the web.
|
46 | >
|
47 | > 💯 Also, featured in [awesome-lit-html].
|
48 |
|
49 | This marks another completion of an important milestone of `app-datepicker` with all the love from the [Web Components community][web-components-community-url] in making this element great and wonderful. As Web Components getting more and more traction and better at providing a web standard way of creating shareable components, it plays an important role in the JavaScript community as many developers depend on a plethora of development tools written in JavaScript for the web to create a better developer experience when developing a library, a component, or even a large scalable application.
|
50 |
|
51 | ![date-pickers-in-different-themes](https://user-images.githubusercontent.com/10607759/158053308-b43cb0e1-f510-4f0e-9804-827a349d5fc7.png)
|
52 |
|
53 | Today, `app-datepicker` has been completely rewritten to adapt to the best of both worlds by leveraging the modern technologies the community most familiar with since year 2018.
|
54 |
|
55 | The following are the list of tools used that makes it shine:
|
56 |
|
57 | 1. [TypeScript]
|
58 | 2. [lit]
|
59 |
|
60 | ## Table of contents <!-- omit in toc -->
|
61 |
|
62 | - [Pre-requisite](#pre-requisite)
|
63 | - [Installation](#installation)
|
64 | - [How to use](#how-to-use)
|
65 | - [Polyfills](#polyfills)
|
66 | - [ES Modules](#es-modules)
|
67 | - [my-app.js](#my-appjs)
|
68 | - [index.html](#indexhtml)
|
69 | - [Browser compatibility](#browser-compatibility)
|
70 | - [Q&A](#qa)
|
71 | - [API references](#api-references)
|
72 | - [Demo](#demo)
|
73 | - [Older versions](#older-versions)
|
74 | - [License](#license)
|
75 |
|
76 | ## Pre-requisite
|
77 |
|
78 | - [ES2019] _(The element is compiled with features targeting ES2019, so it might not work properly without transpilation on older browsers.)_
|
79 | - [lit] >= 2.2.0
|
80 | - [OPTIONAL] [TypeScript] >= 4.5.5 _(TypeScript users only)_
|
81 |
|
82 | ## Installation
|
83 |
|
84 | - NPM
|
85 |
|
86 | ```sh
|
87 | $ npm i app-datepicker@next
|
88 | ```
|
89 |
|
90 | - Alternatively, it can be downloaded from any of the following awesome CDNs:
|
91 |
|
92 | 1. [esm.run/ jsdelivr][jsdelivr-url]
|
93 | 2. [esm.sh][esm-sh-url]
|
94 |
|
95 | ## How to use
|
96 |
|
97 | ### Polyfills
|
98 |
|
99 | Please make sure you have all these features available on the browsers you are supporting. If no, please consider polyfill-ing in order to run the datepicker element.
|
100 |
|
101 | * [Array.prototype.find]
|
102 | * [Intl.DateTimeFormat]
|
103 |
|
104 | The following snippet shows a simple script used in the demo to load polyfills via feature detection on different browsers:
|
105 |
|
106 | ```html
|
107 | <script>
|
108 | if (null == Array.prototype.find) {
|
109 | Object.defineProperty(Array.prototype, 'find', {
|
110 | value: function arrayFind(cb) {
|
111 | var filtered = this.filter(cb);
|
112 | return !filtered.length ? void 0 : filtered[0];
|
113 | },
|
114 | });
|
115 | }
|
116 |
|
117 | if (!window.Intl) {
|
118 | var wa = document.createElement('script');
|
119 | /** NOTE: Pin package version due to https://github.com/andyearnshaw/Intl.js/issues/256 */
|
120 | wa.src = 'https://esm.run/intl@1.2.4/dist/Intl.complete.js';
|
121 | wa.onload = function onLoad() { console.info('🌐 Intl polyfill loaded'); };
|
122 | wa.onerror = console.error;
|
123 | document.head.appendChild(wa);
|
124 | }
|
125 | </script>
|
126 | ```
|
127 |
|
128 | ### ES Modules
|
129 |
|
130 | #### my-app.js
|
131 |
|
132 | ```ts
|
133 | /**
|
134 | * Say you've already installed the element via NPM, simply import the package to your application.
|
135 | * Here I'm using `lit` for developing my application.
|
136 | */
|
137 | import { css, html, LitElement } from 'lit';
|
138 | import { customElement } from 'lit/decorators.js';
|
139 | import 'app-datepicker';
|
140 |
|
141 | const localName = 'my-app';
|
142 |
|
143 | @customElement(localName)
|
144 | export class MyApp extends LitElement {
|
145 | static styles = [
|
146 | css`
|
147 | :host {
|
148 | display: block;
|
149 | }
|
150 |
|
151 | * {
|
152 | box-sizing: border-box;
|
153 | }
|
154 | `
|
155 | ];
|
156 |
|
157 | render() {
|
158 | return html`<app-date-picker></app-date-picker>`;
|
159 | }
|
160 | }
|
161 | ```
|
162 |
|
163 | #### index.html
|
164 |
|
165 | ```html
|
166 | <!doctype html>
|
167 | <html>
|
168 | <!-- Using ES modules to load the app -->
|
169 | <script type="module" src="/my-app.js"></script>
|
170 | ...
|
171 | <body>
|
172 | <my-app>
|
173 | <!-- <AppDatepicker> will be rendered when <MyApp> loads. -->
|
174 | </my-app>
|
175 | </body>
|
176 | ...
|
177 | </html>
|
178 | ```
|
179 |
|
180 | ## Browser compatibility
|
181 |
|
182 | All the elements work in last 2 versions of all evergreen browsers (Chrome/ Edge, Firefox, and Safari). Internet Explorer 11 is no longer supported in favor of the [new Microsoft Edge].
|
183 |
|
184 | Tested on the following browsers:
|
185 |
|
186 | 1. `Chrome/ Edge 100`
|
187 | 2. `Firefox 96`
|
188 | 3. `Safari 15.4`
|
189 |
|
190 | Not tested on the following browsers but it should work with all the polyfills needed:
|
191 |
|
192 | 1. `Edge 18` and below
|
193 | 3. `Safari 13.1` and below
|
194 |
|
195 | ## Q&A
|
196 |
|
197 | 1. Does it work well with [material-components-web-components]?
|
198 |
|
199 | For [material-components-web-components] users, you can create your own custom date picker element by wrapping `app-date-picker` inside [mwc-dialog].
|
200 |
|
201 | <!-- Feasible source code can be viewed [here][mwc-date-picker-url]. -->
|
202 |
|
203 | ```ts
|
204 | // Simplified code snippet
|
205 |
|
206 | class MWCDatePicker extends LitElement {
|
207 | render() {
|
208 | return html`
|
209 | <mwc-dialog>
|
210 | <app-date-picker></app-date-picker>
|
211 |
|
212 | <mwc-button slot="secondaryAction" dialogAction="cancel">cancel</mwc-button>
|
213 | <mwc-button slot="primaryAction" dialogAction="set">set</mwc-button>
|
214 | </mwc-dialog>
|
215 | `;
|
216 | }
|
217 | }
|
218 | ```
|
219 |
|
220 | ## API references
|
221 |
|
222 | - [AppDatePicker]
|
223 | - [AppDatePickerDialog]
|
224 | - [AppDatePickerInput]
|
225 |
|
226 | ## Demo
|
227 |
|
228 | - [`app-datepicker` demo with configurable code snippets]
|
229 |
|
230 | ## Older versions
|
231 |
|
232 | - [`4-5.x`](https://github.com/motss/app-datepicker/tree/4-5.x)
|
233 |
|
234 | ## License
|
235 |
|
236 | [MIT License](http://motss.mit-license.org/) © Rong Sen Ng
|
237 |
|
238 |
|
239 | [`app-datepicker` demo with configurable code snippets]: https://motss.xyz/demos/app-datepicker
|
240 | [AppDatePicker]: /docs/app-date-picker.md
|
241 | [AppDatePickerDialog]: /docs/app-date-picker-dialog.md
|
242 | [AppDatePickerInput]: /docs/app-date-picker-input.md
|
243 | [Array.prototype.find]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
|
244 | [awesome-lit-html]: https://github.com/web-padawan/awesome-lit-html#individual-components
|
245 | [ES2019]: https://kangax.github.io/compat-table/es2016plus/#test-Object.fromEntries
|
246 | [esm-sh-url]: https://esm.sh/app-datepicker@next?target=es2019
|
247 | [Intl.DateTimeFormat]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat
|
248 | [jsdelivr-url]: https://www.jsdelivr.com/package/npm/app-datepicker?version=next&utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
249 | [lit]: https://github.com/lit/lit?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
250 | [material-components-web-components]: https://github.com/material-components/material-components-web-components
|
251 | [mwc-date-picker-url]: https://motss-app.web.app/demo/app-datepicker/mwc-date-picker.js
|
252 | [mwc-dialog]: https://github.com/material-components/material-components-web-components/tree/master/packages/dialog
|
253 | [new Microsoft Edge]: https://blogs.windows.com/msedgedev/2020/01/15/upgrading-new-microsoft-edge-79-chromium
|
254 | [TypeScript]: https://github.com/Microsoft/TypeScript?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
255 | [web-components-community-url]: https://www.webcomponents.org?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
256 | [wre-2019-url]: https://www.deepcrawl.com/blog/news/what-version-of-chrome-is-google-actually-using-for-rendering
|
257 |
|
258 |
|
259 | [string-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String?utm_source=github.com&utm_medium=referral
|
260 | [object-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object?utm_source=github.com&utm_medium=referral
|
261 | [number-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number?utm_source=github.com&utm_medium=referral
|
262 | [boolean-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean?utm_source=github.com&utm_medium=referral
|
263 |
|
264 |
|
265 | [buymeacoffee-badge]: https://flat.badgen.net/badge/icon/buymeacoffee?icon=buymeacoffee&label=motss
|
266 | [tippin-me-badge]: https://badgen.net/badge/%E2%9A%A1%EF%B8%8Ftippin.me/@igarshmyb/F0918E
|
267 | [follow-me-badge]: https://flat.badgen.net/twitter/follow/igarshmyb?icon=twitter
|
268 | [join-discord-badge]: https://badgen.net/discord/members/ps8mCrvTKR?label=app-datepicker&icon=discord
|
269 |
|
270 | [version-badge]: https://flat.badgen.net/npm/v/app-datepicker/next?icon=npm
|
271 | [lit-version-badge]: https://flat.badgen.net/npm/v/lit/latest?icon=npm&label=lit
|
272 | [mit-license-badge]: https://flat.badgen.net/npm/license/app-datepicker
|
273 |
|
274 | [downloads-badge]: https://flat.badgen.net/npm/dm/app-datepicker
|
275 | [total-downloads-badge]: https://flat.badgen.net/npm/dt/app-datepicker?label=total%20downloads
|
276 | [packagephobia-badge]: https://flat.badgen.net/packagephobia/install/app-datepicker@next
|
277 | [bundlephobia-badge]: https://flat.badgen.net/bundlephobia/minzip/app-datepicker@next
|
278 |
|
279 | [ga-ci-badge]: https://github.com/motss/app-datepicker/actions/workflows/ci.yml/badge.svg
|
280 | [ga-ci-helpers-badge]: https://github.com/motss/app-datepicker/actions/workflows/ci-helpers.yml/badge.svg
|
281 | [codecov-badge]: https://codecov.io/gh/motss/app-datepicker/branch/main/graph/badge.svg?token=0M1yaJNDxq
|
282 |
|
283 | [coc-badge]: https://flat.badgen.net/badge/code%20of/conduct/pink
|
284 |
|
285 |
|
286 | [buymeacoffee-url]: https://www.buymeacoffee.com/RLmMhgXFb
|
287 | [tippin-me-url]: https://tippin.me/@igarshmyb
|
288 | [follow-me-url]: https://twitter.com/igarshmyb?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
289 | [join-discord-url]: https://discord.gg/ps8mCrvTKR
|
290 |
|
291 | [version-url]: https://www.npmjs.com/package/app-datepicker/v/next?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
292 | [mit-license-url]: https://github.com/motss/app-datepicker/blob/main/LICENSE?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
293 |
|
294 | [downloads-url]: http://www.npmtrends.com/app-datepicker?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
295 | [packagephobia-url]: https://packagephobia.now.sh/result?p=app-datepicker@next&utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
296 | [bundlephobia-url]: https://bundlephobia.com/result?p=app-datepicker@next&utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|
297 |
|
298 | [ga-ci-url]: https://github.com/motss/app-datepicker/actions/workflows/ci.yml
|
299 | [ga-ci-helpers-url]: https://github.com/motss/app-datepicker/actions/workflows/ci-helpers.yml
|
300 | [codecov-url]: https://codecov.io/gh/motss/app-datepicker
|
301 |
|
302 | [coc-url]: https://github.com/motss/app-datepicker/blob/main/code-of-conduct.md?utm_source=github.com&utm_medium=referral&utm_content=motss/app-datepicker
|