@dreamworld/dw-date-input

@dreamworld/dw-date-input

A LitElement-based web component (<dw-date-input>) that provides a text field for date entry with smart auto-formatting, built-in validation (required, min/max date, future date), and an integrated Litepicker calendar popover for desktop and full-screen modal for mobile/tablet.

---

1. User Guide

Installation & Setup

yarn add @dreamworld/dw-date-input

Basic Usage

import '@dreamworld/dw-date-input/dw-date-input.js';

<dw-date-input
  label="Start Date"
  placeholder="DD/MM/YYYY"
  required
  value="2024-01-15"
  @change=${(e) => console.log(e.detail.value)}
></dw-date-input>

The value property is always read/written in valueFormat (default YYYY-MM-DD). The user types in inputFormat (default DD/MM/YYYY). The component converts between the two automatically.

---

API Reference

Props — <dw-date-input>

Name	Type	Default	Required	Description
name	String	""	No	Name attribute forwarded to the inner input element.
value	String	""	No	Current date value in valueFormat. Set this to pre-fill the field.
label	String	—	No	Floating label shown above the input.
placeholder	String	""	No	Placeholder text shown inside the input.
disabled	Boolean	false	No	Disables the input.
readOnly	Boolean	false	No	Makes the input read-only. Clicking will not open the calendar picker.
required	Boolean	false	No	Marks the input as required. Validation fails when empty.
noLabel	Boolean	false	No	Hides the label.
hint	String	""	No	Helper text shown below the input.
hintPersistent	Boolean	false	No	When true, hint text is always visible regardless of focus.
noHintWrap	Boolean	false	No	Constrains hint text to a single line.
dense	Boolean	false	No	Applies dense (compact) styling.
autoSelect	Boolean	true	No	Auto-selects the text content when the input is focused.
inputFormat	String	"DD/MM/YYYY"	No	Format the user types in. Accepted values: DD/MM/YYYY, MM/DD/YYYY, DD-MM-YYYY, MM-DD-YYYY, etc. Case-insensitive.
valueFormat	String	"YYYY-MM-DD"	No	Format used for the value property and change event.
dateRepresentationFormat	String	"DD MMM YYYY"	No	Format used to display the selected date in the calendar picker header.
minDate	String	—	No	Minimum allowed date (inclusive), in valueFormat. Dates before this trigger a validation error.
maxDate	String	—	No	Maximum allowed date (inclusive), in valueFormat. Dates after this trigger a validation error.
showFutureError	Boolean	false	No	When true, selecting a future date is a validation error.
showFutureWarning	Boolean	false	No	When true, selecting a future date shows a warning (suppressed when an error is active).
supportRelativeDate	Boolean	false	No	When true, typing +N, -N, or +0 resolves to base date ± N days on blur, Enter, or paste. Resolution happens before validation, so minDate/maxDate/showFutureError apply to the resolved date.
relativeDateBase	String	—	No	Anchor date (in valueFormat) used by supportRelativeDate. When omitted or unparseable, today is used as the base.
invalid	Boolean	false	No	Reflects the last validation result. Set externally to force an invalid state.
originalValue	String	""	No	Reference value used with highlightChanged to detect user modifications.
highlightChanged	Boolean	false	No	When true and value !== originalValue, applies a visual highlight. Requires originalValue to be set.
error	String | Function | Object	—	No	Custom error message or function. Overrides internal validation display.
warning	String | Function | Object	—	No	Custom warning message or function.
errorMessages	Object	See below	No	Per-instance override of the default error message strings.
hintInTooltip	Boolean	—	No	When true, shows the hint inside a tooltip on the trailing icon instead of inline.
errorInTooltip	Boolean	—	No	When true, shows the error inside a tooltip on the trailing icon instead of inline.
warningInTooltip	Boolean	—	No	When true, shows the warning inside a tooltip on the trailing icon instead of inline.
hintTooltipActions	Array	—	No	Action buttons to render inside the hint tooltip.
errorTooltipActions	Array	—	No	Action buttons to render inside the error tooltip.
warningTooltipActions	Array	—	No	Action buttons to render inside the warning tooltip.
tipPlacement	String	"bottom-end"	No	Tippy.js placement for all tooltips. See Tippy.js placement docs.
tipExtraOptions	Object	—	No	Extra options forwarded directly to Tippy.js.
iconTrailing	String	"date_range"	No	Material icon name for the trailing icon that opens the calendar.
mobileMode	Boolean	false	No	When true, the calendar opens as a full-screen modal. Input is pointer-events disabled.
tabletMode	Boolean	false	No	When true, applies tablet-specific layout. Input is pointer-events disabled.
zIndex	Number	9999	No	z-index of the calendar popover.
appendTo	String | Element	"parent"	No	DOM element (or "parent") to which the popover is appended.
triggerElement	Element	(auto)	No	Element used as the popover anchor. Defaults to the internal date-input element.

---

Events

Event	detail Shape	Description
change	{ value: string }	Fired when the date value changes — on blur, paste, Enter key, or calendar date selection. value is in valueFormat, or "" for an invalid/cleared entry.
enter	{ value: string }	Fired when the user presses Enter inside the text field.
date-picker-opened	—	Fired when the calendar popover/modal opens.
date-picker-closed	—	Fired when the calendar popover/modal closes.

---

Instance Methods

Method	Returns	Description
focus()	Promise<void>	Focuses the inner text field. Async — awaits updateComplete.
validate()	Boolean	Alias for reportValidity().
reportValidity()	Boolean	Triggers validation and updates the invalid state. Returns true if valid.
checkValidity()	Boolean	Returns true if the current value passes all validation rules without updating the UI.

---

Static Methods

Method	Parameters	Description
DwDateInput.setErrorMessages(messages)	messages: Object	Merges messages into the global default error messages. Affects all <dw-date-input> instances that do not override errorMessages.

---

Validation & Error Messages

Default error messages (can be overridden globally via setErrorMessages or per-instance via the errorMessages prop):

{
  minDate:       "Must be > {minDate}",
  maxDate:       "Must be < {maxDate}",
  minMaxDate:    "Date must be between {minDate} and {maxDate}",
  invalidDate:   "Date is invalid",
  showFutureError: "Future date is not allowed."
}

The placeholders {minDate} and {maxDate} are replaced at runtime with the actual minDate/maxDate prop values.

The warning produced by showFutureWarning is hardcoded to "Future date is selected" in date-input.js and is not configurable via errorMessages.

---

CSS Custom Properties

Property	Default	Description
--dw-date-input-padding	12px 16px 14px	Padding of the <input> element inside the outlined text field.
--dw-popover-border-radius	18px	Border-radius of the calendar popover surface.
--dw-popover-width	360px	Width of the calendar popover.
--dw-popover-min-width	360px	Minimum width of the calendar popover.
--mdc-theme-primary	(MDC theme)	Color applied to the trailing calendar icon and active states when the picker is open.
--mdc-theme-surface	(MDC theme)	Calendar surface background.
--mdc-theme-text-primary-on-surface	(MDC theme)	Primary text color inside the calendar.
--mdc-theme-text-secondary-on-surface	(MDC theme)	Secondary text color (day-of-week label in header).
--mdc-theme-divider-color	(MDC theme)	Color of the divider line below the calendar header.

---

Advanced Usage

Pre-filled value with change highlight

html`
<dw-date-input
  label="Start Date"
  .value=${"2024-06-01"}
  .originalValue=${"2024-06-01"}
  highlightChanged
  @change=${(e) => console.log('New value:', e.detail.value)}
></dw-date-input>
`

When the user changes the date, the field is visually highlighted. Restoring to originalValue removes the highlight.

---

Min/Max date constraint

<dw-date-input
  label="Booking Date"
  min-date="2024-01-01"
  max-date="2024-12-31"
></dw-date-input>

Or in JavaScript (property binding):

el.minDate = '2024-01-01';
el.maxDate = '2024-12-31';

---

Blocking future dates

<!-- Error if future date is entered -->
<dw-date-input show-future-error></dw-date-input>

<!-- Warning (non-blocking) if future date is entered -->
<dw-date-input show-future-warning></dw-date-input>

---

Tooltip mode for hint/error/warning

html`
<dw-date-input
  label="Date"
  hint="Enter date in DD/MM/YYYY"
  hintInTooltip
  .warning=${"Selected date is in the past"}
  warningInTooltip
></dw-date-input>
`

---

Global error message customization

import { DwDateInput } from '@dreamworld/dw-date-input/dw-date-input.js';

DwDateInput.setErrorMessages({
  invalidDate: 'Please enter a valid date.',
  minDate: 'Date must be on or after {minDate}.',
});

---

Custom inputFormat

<!-- US format -->
<dw-date-input input-format="MM/DD/YYYY" label="Date"></dw-date-input>

<!-- ISO input -->
<dw-date-input input-format="YYYY-MM-DD" label="Date"></dw-date-input>

---

Mobile / Tablet mode

<!-- Full-screen calendar modal on mobile -->
<dw-date-input mobile-mode label="Date"></dw-date-input>

<!-- Tablet layout -->
<dw-date-input tablet-mode label="Date"></dw-date-input>

In these modes, the <input> element is pointer-events disabled; date entry is only possible through the calendar or dialog.

---

Arrow-key date increment

When the text field is focused and contains a valid date, pressing Arrow Up increments the date by 1 day and Arrow Down decrements by 1 day. If the field is empty, Arrow Up/Down sets the value to today's date.

---

Relative date shortcuts

<!-- Resolve +N / -N against today -->
<dw-date-input support-relative-date label="Due Date"></dw-date-input>

<!-- Resolve against an explicit base date (e.g., a transaction date) -->
<dw-date-input
  support-relative-date
  .relativeDateBase=${"2024-06-01"}
  label="Due Date"
></dw-date-input>

When supportRelativeDate is true, the user can type +N, -N, or +0 and the input is replaced on blur/Enter/paste with the resolved date:

• +5 → base date + 5 days
• -10 → base date − 10 days
• +0 / -0 → base date

If relativeDateBase is set (in valueFormat), it acts as the anchor; otherwise today is used. An unparseable relativeDateBase silently falls back to today.

The regex is strict — + 5, ++5, bare +, etc. are not treated as relative-date input and fall through to normal date parsing. The resolved date is then run through standard minDate/maxDate/showFutureError validation.

---

dateParse(value, format) Utility

import { dateParse } from '@dreamworld/dw-date-input/date-parse.js';

const result = dateParse('25 Jan 2024', 'DD/MM/YYYY');
// Returns: "25/01/2024"

Parameters:

Parameter	Type	Description
value	String	Raw user input in any supported format (see below).
format	String	Target dayjs-compatible format string the result should be returned in.

Returns: String — the parsed date in format, or null if the input cannot be parsed.

Supported input formats:

Category	Examples
Slash-separated	DD/MM/YYYY, MM/DD/YYYY, D/M/YYYY
Dash-separated	DD-MM-YYYY, MM-DD-YYYY
ISO	YYYY-MM-DD, YYYY/MM/DD
Spaced separators	DD / MM / YYYY, MM / DD / YYYY, YYYY - MM - DD
Month name (abbrev.)	DD MMM YYYY, DD MMM, YYYY, MMM DD YYYY, MMM DD, YYYY
Month name (full)	MMMM D, YYYY, MMMM DD, YYYY
Numeric only	1212 → auto-parsed as day+month using inputFormat
Year-omitted	25 Jan, 01/15 → current year is auto-filled

Behavior notes:

• Month names are case-insensitive.
• For numeric-only input, day/month order follows the provided format.
• If day and month values exceed valid ranges, the parser swaps them automatically.
• Two-digit years (24) are expanded to 2024.

---

currentYearFormat Constant

import { currentYearFormat } from '@dreamworld/dw-date-input/constants.js';

Maps a full-year date format to its corresponding current-year (year-omitted) format.

Full format	Year-omitted format
DD-MM-YYYY	DD-MM
DD/MM/YYYY	DD/MM
MM/DD/YYYY	MM/DD
MM-DD-YYYY	MM-DD
YYYY/MM/DD	MM/DD
YYYY-MM-DD	MM-DD
DD MMM YYYY	DD MMM
MMM DD, YYYY	MMM DD

---

2. Developer Guide / Architecture

Component Hierarchy

DwDateInput  <dw-date-input>          extends DwFormElement(LitElement)
├── DateInput  <date-input>            extends DwInput  (internal text field)
│   ├── dw-icon-button                 (trailing calendar icon)
│   └── dw-tooltip                    (conditional hint/error/warning tooltip)
├── DwDatePicker  <dw-date-picker>     extends DwCompositeDialog  (lazy — rendered only when _pickerOpened)
│   ├── Litepicker instance            (inline calendar, keyboardnav + mobilefriendly plugins)
│   ├── DwDateInput                    (edit mode input inside picker header)
│   └── dw-button (Cancel / Apply)    (edit mode actions)
└── DwDateInputDialog <dw-date-input-dialog>  extends DwCompositeDialog  (modal for mobile/tablet)
    ├── DateInput  <date-input>
    └── dw-button (Cancel / Apply)

Module Responsibilities

File	Exported Name	Role
dw-date-input.js	DwDateInput	Orchestrator. Owns value state, format normalization, validation delegation, picker lifecycle.
date-input.js	DateInput	Low-level text field. Handles raw input, dateParse on blur/paste/Enter, arrow-key date change, format display, and validation error/warning computation.
dw-date-picker.js	DwDatePicker	Litepicker-based calendar dialog (popover on desktop, modal on mobile). Manages picker instance lifecycle.
dw-date-input-dialog.js	DwDateInputDialog	Modal dialog wrapping a DateInput for explicit Apply/Cancel flow. Emits mode-changed when switching to the calendar.
date-parse.js	dateParse	Pure utility. Parses freeform date strings into a specified dayjs format.
constants.js	currentYearFormat	Static map from full formats to year-omitted equivalents.

Design Patterns

Mixin — DwFormElement DwDateInput applies the DwFormElement mixin from @dreamworld/dw-form, integrating it into form validation workflows (checkValidity, reportValidity).

Composition via Lit templates DwDateInput.render() conditionally composes three sub-templates: dateInputTemplate (always rendered), datePickerTemplate (rendered only when _pickerOpened === true), and dateInputDialogTemplate. This lazy-renders the heavy Litepicker calendar.

Strategy pattern — _error / _warning getters DwDateInput exposes _error and _warning as overridable getters. Subclasses can extend DwDateInput, override these getters to inject additional validation logic, and call super to preserve the base behaviour. This avoids conflicts with the public error/warning props that integrators use.

Format normalization All format strings (inputFormat, valueFormat, dateRepresentationFormat) are uppercased internally (_inputFormat, _valueFormat, _dateRepresentationFormat) in willUpdate. This means props are accepted case-insensitively (dd/mm/yyyy and DD/MM/YYYY are both valid).

Development Server

yarn start
# Launches @web/dev-server with demo/index.html