@maihcx/super-date 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maihcx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# SuperDate
+
+TypeScript date/time input enhancer. Replaces the native browser date-picker chrome with a fully custom, format-aware overlay — while still delegating the actual popup to the OS so you never re-implement a calendar or clock widget.
+
+Supports `input[type="date"]`, `input[type="time"]`, and `input[type="datetime-local"]`.
+
+## Features
+
+| Feature | Detail |
+|---|---|
+| **3 input types** | `date`, `time`, and `datetime-local` all supported |
+| **Auto-observe** | `SuperDate.bind('.selector')` watches the DOM via `MutationObserver` — inputs added later are automatically enhanced |
+| **Custom format** | Global default or per-element via `data-date-format`, `data-time-format`, `data-date-time-delimiter` |
+| **Keyboard editing** | `↑ ↓` step values, `← →` move segments, `0–9` type digits, auto-advance on completion |
+| **Copy / Paste** | Parses pasted text against configured format + common fallbacks |
+| **Native picker** | Calendar / clock icon opens the OS picker; `input.value` stays as ISO string |
+| **Zero dependencies** | Plain TypeScript, no runtime deps |
+
+## Install
+
+```bash
+npm install superdate   # if published
+# or copy dist/ into your project
+```
+
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+Outputs:
+
+| File | Format |
+|---|---|
+| `dist/super-date.esm.js` | ES Module |
+| `dist/super-date.esm.min.js` | ES Module (minified) |
+| `dist/super-date.umd.js` | UMD (browser global `SuperDate`) |
+| `dist/super-date.min.js` | UMD (minified) |
+
+## Usage
+
+### Via `<script>` tag
+
+```html
+<link rel="stylesheet" href="dist/super-date.min.css" />
+<script src="dist/super-date.umd.js"></script>
+<script>
+  SuperDate.bind('.sd', { format: 'dd/MM/yyyy' });
+</script>
+```
+
+### ES Module
+
+```js
+import SuperDate from './dist/super-date.esm.js';
+SuperDate.bind('.sd', { format: 'dd/MM/yyyy' });
+```
+
+### TypeScript / bundler
+
+```ts
+import SuperDate from 'superdate';
+SuperDate.bind('.sd');
+```
+
+## API
+
+### `SuperDate.bind(selector, options?)`
+
+Enhances all current **and future** `<input type="date">`, `<input type="time">`, and `<input type="datetime-local">` elements matching `selector`.
+
+```ts
+SuperDate.bind('.sd', {
+  format:            'dd/MM/yyyy', // date display format
+  timeFormat:        'HH:mm',      // time display format
+  dateTimeDelimiter: ' ',          // separator between date and time parts
+  locale:            'vi-VN',      // locale (reserved for future i18n)
+});
+```
+
+Returns `this` for chaining.
+
+### `SuperDate.init(el, options?)`
+
+Manually enhance a single element. Returns the `SuperDateInstance`.
+
+```ts
+const el = document.querySelector('#my-input') as HTMLInputElement;
+SuperDate.init(el, { format: 'yyyy/MM/dd' });
+```
+
+### `SuperDate.destroy(el)`
+
+Remove the overlay and restore the original native input.
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `format` | `string` | `'dd/MM/yyyy'` | Display format for `date` and the date part of `datetime-local` inputs |
+| `timeFormat` | `string` | `'HH:mm'` | Display format for `time` and the time part of `datetime-local` inputs |
+| `dateTimeDelimiter` | `string` | `' '` | String inserted between date and time parts in `datetime-local` inputs |
+| `locale` | `string` | `navigator.language` | Locale (reserved) |
+
+## Per-element overrides (data attributes)
+
+```html
+<!-- date -->
+<input type="date" data-date-format="yyyy/MM/dd" />
+
+<!-- time -->
+<input type="time" data-time-format="HH:mm:ss" />
+
+<!-- datetime-local — all three can be combined -->
+<input type="datetime-local"
+  data-date-format="dd/MM/yyyy"
+  data-time-format="HH:mm:ss"
+  data-date-time-delimiter=" | " />
+```
+
+Per-element attributes always take priority over `bind()` options.
+
+## Supported tokens
+
+### Date tokens
+
+| Token | Description | Example |
+|---|---|---|
+| `yyyy` | 4-digit year | `2025` |
+| `yy` | 2-digit year | `25` |
+| `MM` | Month, zero-padded | `03` |
+| `M` | Month, no padding | `3` |
+| `dd` | Day, zero-padded | `07` |
+| `d` | Day, no padding | `7` |
+
+### Time tokens
+
+| Token | Description | Example |
+|---|---|---|
+| `HH` | Hours 24h, zero-padded | `09`, `23` |
+| `H` | Hours 24h, no padding | `9`, `23` |
+| `hh` | Hours 12h, zero-padded | `09`, `11` |
+| `h` | Hours 12h, no padding | `9`, `11` |
+| `mm` | Minutes, zero-padded | `05`, `59` |
+| `ss` | Seconds, zero-padded | `00`, `59` |
+
+> **Note:** `MM` = months (uppercase), `mm` = minutes (lowercase).
+
+## CSS variables
+
+Override the overlay appearance per-element or globally:
+
+```css
+.superdate-overlay {
+  --superdate-active-bg:          #2563eb;  /* active segment background */
+  --superdate-active-color:       #fff;     /* active segment text */
+  --superdate-placeholder-color:  #9ca3af;  /* empty segment placeholder */
+  --superdate-sep-color:          inherit;  /* separator / literal color */
+}
+```
+
+## Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `0–9` | Type digit into active segment, auto-advance when full |
+| `↑` / `↓` | Increment / decrement active segment value |
+| `←` / `→` | Move to previous / next segment |
+| `Tab` / `Shift+Tab` | Move to next / previous segment |
+| `Backspace` | Erase last typed digit in buffer |
+| `Escape` | Deactivate / clear selection |
+| `Ctrl+A` | Select all segments |
+| `Ctrl+C` | Copy selected segments as formatted text |
+| Click & drag | Multi-segment selection |
+| Double-click | Select all segments |
+
+## Input value
+
+The underlying `input.value` always stays in native ISO format — SuperDate only changes the **visual overlay**:
+
+| Input type | `input.value` format |
+|---|---|
+| `date` | `yyyy-MM-dd` |
+| `time` | `HH:mm:ss` |
+| `datetime-local` | `yyyy-MM-ddTHH:mm:ss` |
+
+## License
+
+MIT

package/dist/super-date.css

@@ -0,0 +1,86 @@
+input.superdate-input::-webkit-datetime-edit,
+input.superdate-input::-webkit-inner-spin-button,
+input.superdate-input::-webkit-clear-button,
+input.superdate-input::-webkit-calendar-picker-indicator {
+  display: none !important;
+  opacity: 0 !important;
+  width: 0 !important;
+}
+input.superdate-input {
+  caret-color: transparent;
+  color: transparent !important;
+  position: relative;
+}
+
+/* Overlay wrapper */
+.superdate-wrapper {
+  position: relative;
+  display: inline-block;
+  width: fit-content;
+}
+
+/* The visible overlay */
+.superdate-overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  padding: 0 8px;
+  pointer-events: none;
+  font: inherit;
+  letter-spacing: inherit;
+  white-space: nowrap;
+  overflow: hidden;
+  box-sizing: border-box;
+  gap: 0;
+  /* prevent browser text selection interfering with drag */
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.superdate-seg {
+  position: relative;
+  display: inline-block;
+  border-radius: 2px;
+  transition: background 0.1s;
+  white-space: pre;
+}
+
+.superdate-seg[data-token] {
+  pointer-events: auto;
+  cursor: text;
+  min-width: 1ch;
+  text-align: center;
+}
+
+/* Single-seg focus OR multi-seg drag selection — same colour, same class */
+.superdate-seg[data-token].active {
+  background: var(--superdate-active-bg, #2563eb);
+  color: var(--superdate-active-color, #fff);
+  border-radius: 3px;
+}
+
+.superdate-seg[data-token].empty {
+  color: var(--superdate-placeholder-color, #9ca3af);
+}
+
+.superdate-seg:not([data-token]) {
+  color: var(--superdate-sep-color, inherit);
+  pointer-events: none;
+}
+
+/* Calendar icon area */
+.superdate-icon {
+  pointer-events: auto;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  margin-left: auto;
+  padding-left: 6px;
+  opacity: 0.5;
+  transition: opacity 0.15s;
+  flex-shrink: 0;
+}
+.superdate-icon:hover { opacity: 1; }
+
+/*# sourceMappingURL=super-date.css.map */

package/dist/super-date.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["index.css"],"names":[],"mappings":"AAAA;;;;EAIE,wBAAwB;EACxB,qBAAqB;EACrB,mBAAmB;AACrB;AACA;EACE,wBAAwB;EACxB,6BAA6B;EAC7B,kBAAkB;AACpB;;AAEA,oBAAoB;AACpB;EACE,kBAAkB;EAClB,qBAAqB;EACrB,kBAAkB;AACpB;;AAEA,wBAAwB;AACxB;EACE,kBAAkB;EAClB,QAAQ;EACR,aAAa;EACb,mBAAmB;EACnB,cAAc;EACd,oBAAoB;EACpB,aAAa;EACb,uBAAuB;EACvB,mBAAmB;EACnB,gBAAgB;EAChB,sBAAsB;EACtB,MAAM;EACN,yDAAyD;EACzD,iBAAiB;EACjB,yBAAyB;AAC3B;;AAEA;EACE,kBAAkB;EAClB,qBAAqB;EACrB,kBAAkB;EAClB,2BAA2B;EAC3B,gBAAgB;AAClB;;AAEA;EACE,oBAAoB;EACpB,YAAY;EACZ,cAAc;EACd,kBAAkB;AACpB;;AAEA,2EAA2E;AAC3E;EACE,+CAA+C;EAC/C,0CAA0C;EAC1C,kBAAkB;AACpB;;AAEA;EACE,kDAAkD;AACpD;;AAEA;EACE,0CAA0C;EAC1C,oBAAoB;AACtB;;AAEA,uBAAuB;AACvB;EACE,oBAAoB;EACpB,eAAe;EACf,aAAa;EACb,mBAAmB;EACnB,iBAAiB;EACjB,iBAAiB;EACjB,YAAY;EACZ,yBAAyB;EACzB,cAAc;AAChB;AACA,wBAAwB,UAAU,EAAE","file":"super-date.css","sourcesContent":["input.superdate-input::-webkit-datetime-edit,\ninput.superdate-input::-webkit-inner-spin-button,\ninput.superdate-input::-webkit-clear-button,\ninput.superdate-input::-webkit-calendar-picker-indicator {\n  display: none !important;\n  opacity: 0 !important;\n  width: 0 !important;\n}\ninput.superdate-input {\n  caret-color: transparent;\n  color: transparent !important;\n  position: relative;\n}\n\n/* Overlay wrapper */\n.superdate-wrapper {\n  position: relative;\n  display: inline-block;\n  width: fit-content;\n}\n\n/* The visible overlay */\n.superdate-overlay {\n  position: absolute;\n  inset: 0;\n  display: flex;\n  align-items: center;\n  padding: 0 8px;\n  pointer-events: none;\n  font: inherit;\n  letter-spacing: inherit;\n  white-space: nowrap;\n  overflow: hidden;\n  box-sizing: border-box;\n  gap: 0;\n  /* prevent browser text selection interfering with drag */\n  user-select: none;\n  -webkit-user-select: none;\n}\n\n.superdate-seg {\n  position: relative;\n  display: inline-block;\n  border-radius: 2px;\n  transition: background 0.1s;\n  white-space: pre;\n}\n\n.superdate-seg[data-token] {\n  pointer-events: auto;\n  cursor: text;\n  min-width: 1ch;\n  text-align: center;\n}\n\n/* Single-seg focus OR multi-seg drag selection — same colour, same class */\n.superdate-seg[data-token].active {\n  background: var(--superdate-active-bg, #2563eb);\n  color: var(--superdate-active-color, #fff);\n  border-radius: 3px;\n}\n\n.superdate-seg[data-token].empty {\n  color: var(--superdate-placeholder-color, #9ca3af);\n}\n\n.superdate-seg:not([data-token]) {\n  color: var(--superdate-sep-color, inherit);\n  pointer-events: none;\n}\n\n/* Calendar icon area */\n.superdate-icon {\n  pointer-events: auto;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  margin-left: auto;\n  padding-left: 6px;\n  opacity: 0.5;\n  transition: opacity 0.15s;\n  flex-shrink: 0;\n}\n.superdate-icon:hover { opacity: 1; }\n"]}