@iyulab/components 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.27.0] - 2026-08-08
+
+### Added
+
+- **`formatNumber`/`formatCurrency`/`formatDate` utilities** (`utilities/format.ts`). Thin
+  wrappers around `Intl.NumberFormat`/`Intl.DateTimeFormat` that default to the active
+  `Locale.get()` locale. `formatCurrency` has no default currency — callers must pass one
+  explicitly.
+- **`u-date-picker`** — a single-date picker form control (`UFormControlElement`), matching
+  the value contract of a native `input[type=date]` (ISO `YYYY-MM-DD`). Renders a calendar
+  grid in a popover with full keyboard navigation (arrow keys, Home/End, Enter/Space, Escape)
+  following the WAI-ARIA Date Picker Dialog pattern. `min`/`max` mark out-of-range days
+  `aria-disabled` (focusable but not selectable, so keyboard users can still perceive and
+  navigate past them) and drive `rangeUnderflow`/`rangeOverflow` validity. Date ranges and
+  `datetime-local` are out of scope for this release.
+
 ## [1.26.0] - 2026-08-07
 
 ### Added

package/README.md

@@ -70,7 +70,7 @@ npx skills add ./node_modules/@iyulab/components
 
 **Buttons & Actions** — `u-button`, `u-button-group`, `u-icon-button`, `u-copy-button`, `u-chip`
 
-**Form Controls** — `u-input`, `u-textarea`, `u-select`, `u-checkbox`, `u-radio`, `u-switch`, `u-slider`, `u-rating`, `u-field`, `u-form`, `u-option`
+**Form Controls** — `u-input`, `u-textarea`, `u-select`, `u-date-picker`, `u-checkbox`, `u-radio`, `u-switch`, `u-slider`, `u-rating`, `u-field`, `u-form`, `u-option`
 
 **Overlay & Floating** — `u-dialog`, `u-drawer`, `u-popover`, `u-tooltip`
 

package/dist/_virtual/_glob-assets_raw/calendar.svg.02c3abd8.js

@@ -0,0 +1,4 @@
+//#region \0glob-assets_raw/calendar.svg.02c3abd8
+var calendar_svg_default = "<svg\n  xmlns=\"http://www.w3.org/2000/svg\"\n  width=\"24\"\n  height=\"24\"\n  viewBox=\"0 0 24 24\"\n  fill=\"none\"\n  stroke=\"currentColor\"\n  stroke-width=\"2\"\n  stroke-linecap=\"round\"\n  stroke-linejoin=\"round\"\n>\n  <path stroke=\"none\" d=\"M0 0h24v24H0z\" fill=\"none\"/>\n  <path d=\"M4 7a2 2 0 0 1 2 -2h12a2 2 0 0 1 2 2v12a2 2 0 0 1 -2 2h-12a2 2 0 0 1 -2 -2v-12z\" />\n  <path d=\"M16 3v4\" />\n  <path d=\"M8 3v4\" />\n  <path d=\"M4 11h16\" />\n  <path d=\"M11 15h1\" />\n  <path d=\"M12 15v3\" />\n</svg>\n";
+//#endregion
+export { calendar_svg_default as default };

package/dist/components/date-picker/UDatePicker.d.ts

@@ -0,0 +1,70 @@
+import { PropertyValues } from 'lit';
+import { UFormControlElement } from '../UFormControlElement.js';
+import { UPopover } from '../popover/UPopover.js';
+/**
+ * A single-date-selection form control. The value follows the same convention as the
+ * native `input[type=date]`: an ISO `YYYY-MM-DD` string.
+ *
+ * The calendar week always starts on Sunday, regardless of locale — harmless for the
+ * locales this library currently ships (en/ko), but not correct for locales where Monday
+ * (most of Europe) or Saturday is conventional. Fix when a consumer needs it: derive the
+ * first day of week from `Intl.Locale(locale).weekInfo?.firstDay`, falling back to Sunday
+ * where unsupported.
+ *
+ * @csspart field - the u-field element
+ * @csspart container - the element wrapping the trigger area
+ * @csspart popover - the popover element showing the calendar
+ * @csspart calendar - the calendar container
+ * @csspart calendar-header - the month navigation header
+ * @csspart calendar-title - the "Month Year" title
+ * @csspart calendar-weekdays - the weekday header row
+ * @csspart calendar-grid - the date grid
+ * @csspart day - a date cell button
+ *
+ * @cssprop --date-picker-popover-width - width of the calendar popover (default: 296px, independent of trigger width — a fixed-width calendar reads more naturally)
+ *
+ * @event change - fires when the user clicks a date cell, confirms via keyboard, or clicks the clear button.
+ *   Programmatic value assignment does not fire it (same contract as native form controls).
+ */
+export declare class UDatePicker extends UFormControlElement<string> {
+    static styles: import('lit').CSSResultGroup[];
+    /** Minimum value (ISO YYYY-MM-DD) — dates before this cannot be selected. */
+    min?: string;
+    /** Maximum value (ISO YYYY-MM-DD) — dates after this cannot be selected. */
+    max?: string;
+    /** Whether to show the clear button */
+    clearable: boolean;
+    /** Placeholder text (shown on the trigger when there is no value) */
+    placeholder?: string;
+    containerEl?: HTMLElement;
+    popoverEl?: UPopover;
+    /** Unique id wiring the combobox's `aria-controls` to the calendar dialog — mirrors USelect's `listboxId`. */
+    private readonly calendarId;
+    private open;
+    private viewDate;
+    private focusedDate;
+    private grabFocusOnUpdate;
+    protected updated(changed: PropertyValues): void;
+    render(): import('lit-html').TemplateResult<1>;
+    private renderCalendar;
+    private renderDay;
+    private isOutOfRange;
+    private focusDayButton;
+    private selectDay;
+    private handlePrevMonth;
+    private handleNextMonth;
+    private navigateMonth;
+    private handleDayKeydown;
+    private moveFocus;
+    private handlePopoverShow;
+    private handlePopoverHide;
+    private handleClearClick;
+    private emitChange;
+    protected setValidity(): void;
+    reset(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-date-picker': UDatePicker;
+    }
+}

package/dist/components/date-picker/UDatePicker.js

@@ -0,0 +1,306 @@
+import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorateMetadata.js";
+import __decorate from "../../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
+import { UFormControlElement } from "../UFormControlElement.js";
+import "../icon/UIcon.js";
+import "../icon-button/UIconButton.js";
+import { Locale } from "../../utilities/Locale.js";
+import "../field/UField.js";
+import { UPopover } from "../popover/UPopover.js";
+import { formatDate } from "../../utilities/format.js";
+import { styles } from "./UDatePicker.styles.js";
+import { html } from "lit";
+import { customElement, property, query, state } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+//#region src/components/date-picker/UDatePicker.ts
+function parseISODate(iso) {
+	const [y, m, d] = iso.split("-").map(Number);
+	return new Date(y, m - 1, d);
+}
+function toISODate(date) {
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+function isSameDay(a, b) {
+	return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+function startOfMonth(date) {
+	return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+function addMonths(date, delta) {
+	return new Date(date.getFullYear(), date.getMonth() + delta, 1);
+}
+function addDays(date, delta) {
+	return new Date(date.getFullYear(), date.getMonth(), date.getDate() + delta);
+}
+function daysInMonth(date) {
+	return new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate();
+}
+/** Cells to render for the calendar grid — leading `null`s pad the previous month's weekday offset. */
+function buildMonthGrid(viewDate) {
+	const startOffset = startOfMonth(viewDate).getDay();
+	const total = daysInMonth(viewDate);
+	const cells = [];
+	for (let i = 0; i < startOffset; i++) cells.push(null);
+	for (let d = 1; d <= total; d++) cells.push(new Date(viewDate.getFullYear(), viewDate.getMonth(), d));
+	return cells;
+}
+/** Splits the flat cell list into 7-day weeks — the `role="row"` grouping the APG grid pattern expects. */
+function chunkWeeks(cells) {
+	const weeks = [];
+	for (let i = 0; i < cells.length; i += 7) weeks.push(cells.slice(i, i + 7));
+	return weeks;
+}
+/** 2023-01-01 was a Sunday — a fixed reference date that always yields Sun..Sat order regardless of today. */
+function getWeekdayLabels(locale) {
+	const formatter = new Intl.DateTimeFormat(locale ?? Locale.get(), { weekday: "narrow" });
+	const sunday = new Date(2023, 0, 1);
+	return Array.from({ length: 7 }, (_, i) => formatter.format(addDays(sunday, i)));
+}
+var UDatePicker = class UDatePicker extends UFormControlElement {
+	constructor(..._args) {
+		super(..._args);
+		this.clearable = false;
+		this.calendarId = `u-date-picker-calendar-${Math.random().toString(36).slice(2, 8)}`;
+		this.open = false;
+		this.viewDate = startOfMonth(/* @__PURE__ */ new Date());
+		this.focusedDate = /* @__PURE__ */ new Date();
+		this.grabFocusOnUpdate = false;
+		this.handlePrevMonth = () => this.navigateMonth(-1);
+		this.handleNextMonth = () => this.navigateMonth(1);
+		this.handleDayKeydown = (e, date) => {
+			switch (e.key) {
+				case "ArrowRight":
+					e.preventDefault();
+					this.moveFocus(date, 1);
+					break;
+				case "ArrowLeft":
+					e.preventDefault();
+					this.moveFocus(date, -1);
+					break;
+				case "ArrowDown":
+					e.preventDefault();
+					this.moveFocus(date, 7);
+					break;
+				case "ArrowUp":
+					e.preventDefault();
+					this.moveFocus(date, -7);
+					break;
+				case "Home":
+					e.preventDefault();
+					this.moveFocus(date, -date.getDay());
+					break;
+				case "End":
+					e.preventDefault();
+					this.moveFocus(date, 6 - date.getDay());
+					break;
+				case "Enter":
+				case " ":
+					e.preventDefault();
+					this.selectDay(date);
+					break;
+				case "Escape":
+					e.preventDefault();
+					this.popoverEl?.hide();
+					this.containerEl?.focus();
+			}
+		};
+		this.handlePopoverShow = () => {
+			this.open = true;
+			this.grabFocusOnUpdate = true;
+			const base = this.value ? parseISODate(this.value) : /* @__PURE__ */ new Date();
+			this.viewDate = startOfMonth(base);
+			this.focusedDate = base;
+		};
+		this.handlePopoverHide = () => {
+			this.open = false;
+		};
+		this.handleClearClick = (e) => {
+			e.preventDefault();
+			e.stopPropagation();
+			const hadValue = !!this.value;
+			this.value = void 0;
+			if (hadValue) this.emitChange();
+			this.containerEl?.focus();
+		};
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	updated(changed) {
+		super.updated(changed);
+		if (changed.has("value")) this.internals?.setFormValue(this.value ?? "");
+		if (changed.has("open") && this.open || changed.has("focusedDate") && this.open && this.grabFocusOnUpdate) {
+			this.grabFocusOnUpdate = false;
+			this.popoverEl?.updateComplete.then(() => this.focusDayButton(this.focusedDate));
+		}
+	}
+	render() {
+		const displayText = this.value ? formatDate(this.value) : "";
+		return html`
+      <u-field part="field"
+        ?required=${this.required}
+        ?disabled=${this.disabled}
+        ?invalid=${this.invalid}
+        .label=${this.label}
+        .description=${this.description}
+        .validationMessage=${this.validationMessage}
+      >
+        <div class="container" part="container"
+          tabindex=${this.disabled ? "-1" : "0"}
+          role="combobox"
+          aria-haspopup="dialog"
+          aria-expanded=${this.open}
+          aria-label=${ifDefined(this.label)}
+          aria-description=${ifDefined(this.description)}
+          aria-controls=${this.calendarId}
+        >
+          <span class="text-content ${!displayText ? "placeholder" : ""}">${displayText || this.placeholder || ""}</span>
+          <u-icon class="suffix-item"
+            ?hidden=${!this.clearable || !this.value || this.disabled || this.readonly}
+            lib="internal"
+            name="x"
+            @click=${this.handleClearClick}
+          ></u-icon>
+          <u-icon class="suffix-item"
+            lib="internal"
+            name="calendar"
+          ></u-icon>
+        </div>
+      </u-field>
+
+      <u-popover part="popover"
+        id=${this.calendarId}
+        role="dialog"
+        aria-label="Choose date"
+        for=".container"
+        trigger="click"
+        strategy="fixed"
+        placement="bottom-start"
+        offset="4"
+        @show=${this.handlePopoverShow}
+        @hide=${this.handlePopoverHide}
+      >
+        ${this.open ? this.renderCalendar() : ""}
+      </u-popover>
+    `;
+	}
+	renderCalendar() {
+		const cells = buildMonthGrid(this.viewDate);
+		const monthLabel = formatDate(this.viewDate, {
+			year: "numeric",
+			month: "long"
+		});
+		const weekdayLabels = getWeekdayLabels();
+		return html`
+      <div class="calendar" part="calendar">
+        <div class="calendar-header" part="calendar-header">
+          <u-icon-button lib="internal" name="chevron-left" aria-label="Previous month" @click=${this.handlePrevMonth}></u-icon-button>
+          <span class="calendar-title" part="calendar-title">${monthLabel}</span>
+          <u-icon-button lib="internal" name="chevron-right" aria-label="Next month" @click=${this.handleNextMonth}></u-icon-button>
+        </div>
+        <div class="calendar-weekdays" part="calendar-weekdays" role="row">
+          ${weekdayLabels.map((w) => html`<span class="weekday" role="columnheader">${w}</span>`)}
+        </div>
+        <div class="calendar-grid" part="calendar-grid" role="grid">
+          ${chunkWeeks(cells).map((week) => html`
+            <div class="calendar-week" part="calendar-week" role="row">
+              ${week.map((date) => date ? this.renderDay(date) : html`<span class="day-empty" role="gridcell" aria-hidden="true"></span>`)}
+            </div>
+          `)}
+        </div>
+      </div>
+    `;
+	}
+	renderDay(date) {
+		const selected = this.value ? isSameDay(date, parseISODate(this.value)) : false;
+		const focused = isSameDay(date, this.focusedDate);
+		const today = isSameDay(date, /* @__PURE__ */ new Date());
+		const outOfRange = this.isOutOfRange(date);
+		return html`
+      <button type="button" class="day" part="day"
+        role="gridcell"
+        data-iso=${toISODate(date)}
+        tabindex=${focused ? 0 : -1}
+        aria-selected=${selected}
+        aria-disabled=${outOfRange}
+        ?data-today=${today}
+        @click=${() => this.selectDay(date)}
+        @keydown=${(e) => this.handleDayKeydown(e, date)}
+        @focus=${() => {
+			this.focusedDate = date;
+		}}
+      >${date.getDate()}</button>
+    `;
+	}
+	isOutOfRange(date) {
+		if (this.min && date.getTime() < parseISODate(this.min).getTime()) return true;
+		if (this.max && date.getTime() > parseISODate(this.max).getTime()) return true;
+		return false;
+	}
+	focusDayButton(date) {
+		const iso = toISODate(date);
+		this.renderRoot.querySelector(`button.day[data-iso="${iso}"]`)?.focus();
+	}
+	selectDay(date) {
+		if (this.isOutOfRange(date)) return;
+		const iso = toISODate(date);
+		const changed = iso !== this.value;
+		this.value = iso;
+		if (changed) this.emitChange();
+		this.popoverEl?.hide();
+		this.containerEl?.focus();
+	}
+	navigateMonth(delta) {
+		this.grabFocusOnUpdate = false;
+		const next = addMonths(this.viewDate, delta);
+		this.viewDate = next;
+		const clampedDay = Math.min(this.focusedDate.getDate(), daysInMonth(next));
+		this.focusedDate = new Date(next.getFullYear(), next.getMonth(), clampedDay);
+	}
+	moveFocus(from, deltaDays) {
+		this.grabFocusOnUpdate = true;
+		const next = addDays(from, deltaDays);
+		if (next.getMonth() !== this.viewDate.getMonth() || next.getFullYear() !== this.viewDate.getFullYear()) this.viewDate = startOfMonth(next);
+		this.focusedDate = next;
+	}
+	emitChange() {
+		if (!this.novalidate) this.validate();
+		this.dispatchEvent(new Event("change", {
+			bubbles: true,
+			composed: true
+		}));
+	}
+	setValidity() {
+		let flags = {};
+		let message = "";
+		if (this.required && !this.value) {
+			flags = { valueMissing: true };
+			message = Locale.getValue("valueMissing");
+		} else if (this.value && this.min && parseISODate(this.value).getTime() < parseISODate(this.min).getTime()) {
+			flags = { rangeUnderflow: true };
+			message = Locale.getValue("rangeUnderflow", { min: this.min });
+		} else if (this.value && this.max && parseISODate(this.value).getTime() > parseISODate(this.max).getTime()) {
+			flags = { rangeOverflow: true };
+			message = Locale.getValue("rangeOverflow", { max: this.max });
+		}
+		this.commit(flags, message, this.containerEl ?? void 0);
+	}
+	reset() {
+		this.value = void 0;
+		this.invalid = false;
+	}
+};
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], UDatePicker.prototype, "min", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], UDatePicker.prototype, "max", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Boolean)], UDatePicker.prototype, "clearable", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], UDatePicker.prototype, "placeholder", void 0);
+__decorate([query(".container", true), __decorateMetadata("design:type", typeof HTMLElement === "undefined" ? Object : HTMLElement)], UDatePicker.prototype, "containerEl", void 0);
+__decorate([query("u-popover", true), __decorateMetadata("design:type", typeof UPopover === "undefined" ? Object : UPopover)], UDatePicker.prototype, "popoverEl", void 0);
+__decorate([state(), __decorateMetadata("design:type", Boolean)], UDatePicker.prototype, "open", void 0);
+__decorate([state(), __decorateMetadata("design:type", typeof Date === "undefined" ? Object : Date)], UDatePicker.prototype, "viewDate", void 0);
+__decorate([state(), __decorateMetadata("design:type", typeof Date === "undefined" ? Object : Date)], UDatePicker.prototype, "focusedDate", void 0);
+UDatePicker = __decorate([customElement("u-date-picker")], UDatePicker);
+//#endregion
+export { UDatePicker };

package/dist/components/date-picker/UDatePicker.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import('lit').CSSResult;

package/dist/components/date-picker/UDatePicker.styles.js

@@ -0,0 +1,147 @@
+import { css } from "lit";
+//#region src/components/date-picker/UDatePicker.styles.ts
+var styles = css`
+  :host {
+    --date-picker-popover-width: 296px;
+  }
+
+  :host {
+    position: relative;
+    display: var(--u-date-picker-display, inline-block);
+    width: var(--u-date-picker-width, auto);
+    color: var(--u-txt-color, #212121);
+    font-size: inherit;
+    font-family: var(--u-font-base);
+  }
+
+  .container {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.4em;
+    padding: 0.3em 0.6em;
+    border: 1px solid var(--u-input-border-color, #E0E0E0);
+    border-radius: 0.25em;
+    background-color: var(--u-input-bg-color, #FFFFFF);
+    cursor: pointer;
+    transition: border-color var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1)),
+      box-shadow var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1));
+  }
+  :host([readonly]) .container,
+  :host([disabled]) .container {
+    cursor: not-allowed;
+    border-color: var(--u-border-color-weak, #EEEEEE);
+    background-color: var(--u-bg-color-disabled, #FAFAFA);
+  }
+  :host(:not([readonly]):not([disabled])) .container:hover {
+    box-shadow: 0 0 0 1px var(--u-input-border-color-hover, #BDBDBD);
+  }
+  :host(:not([readonly]):not([disabled])) .container:focus-within {
+    box-shadow: 0 0 0 1px var(--u-input-border-color-focus, #1565C0);
+  }
+  :host([invalid]:not([readonly]):not([disabled])) .container {
+    box-shadow: 0 0 0 1px var(--u-input-border-color-invalid, #C62828);
+  }
+
+  .text-content {
+    flex: 1 0 auto;
+    min-width: 0;
+    font-size: 1em;
+    line-height: 1.5;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .text-content.placeholder {
+    color: var(--u-txt-color-weak, #757575);
+  }
+
+  .suffix-item {
+    color: var(--u-icon-color, #616161);
+    font-size: 1em;
+    transition: color var(--u-duration-normal, 220ms) var(--u-ease-standard, cubic-bezier(0.2, 0, 0, 1));
+  }
+  .suffix-item:hover {
+    color: var(--u-icon-color-hover, #1565C0);
+  }
+
+  u-popover {
+    width: var(--date-picker-popover-width);
+    padding: 8px;
+    border: 1px solid var(--u-border-color, #E0E0E0);
+    border-radius: var(--u-radius-lg, 6px);
+    background-color: var(--u-panel-bg-color, #FFFFFF);
+    box-shadow: var(--u-shadow-lg, 0 4px 12px rgba(0, 0, 0, 0.16), 0 2px 4px rgba(0, 0, 0, 0.06));
+  }
+
+  .calendar-header {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 4px 8px;
+  }
+  .calendar-title {
+    font-size: var(--u-text-label-size, 13px);
+    font-weight: var(--u-text-label-weight, 600);
+  }
+
+  .calendar-weekdays,
+  .calendar-grid {
+    display: grid;
+    grid-template-columns: repeat(7, 1fr);
+  }
+  .calendar-weekdays {
+    padding-bottom: 4px;
+  }
+  /* role="row" wrapper for APG grid semantics — display:contents keeps it out of the
+     CSS grid track so its day cells still lay out as direct grid items. */
+  .calendar-week {
+    display: contents;
+  }
+  .weekday {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: var(--u-text-caption-size, 12px);
+    color: var(--u-txt-color-weak, #757575);
+  }
+
+  .day,
+  .day-empty {
+    aspect-ratio: 1;
+  }
+  .day {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border: none;
+    border-radius: var(--u-radius-circle, 50%);
+    background: transparent;
+    color: var(--u-txt-color, #212121);
+    font-size: 1em;
+    font-family: inherit;
+    cursor: pointer;
+  }
+  .day:hover:not([aria-disabled="true"]) {
+    background-color: var(--u-bg-color-hover, #F5F5F5);
+  }
+  .day:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 2px var(--u-input-border-color-focus, #1565C0);
+  }
+  .day[data-today] {
+    font-weight: 700;
+    color: var(--u-primary-color, #1976D2);
+  }
+  .day[aria-selected="true"] {
+    background-color: var(--u-primary-color, #1976D2);
+    color: var(--u-primary-txt-color, #FFFFFF);
+  }
+  .day[aria-disabled="true"] {
+    color: var(--u-txt-color-disabled, #BDBDBD);
+    cursor: not-allowed;
+  }
+`;
+//#endregion
+export { styles };

package/dist/components/input/UInput.js

@@ -5,8 +5,8 @@ import "../spinner/USpinner.js";
 import "../icon/UIcon.js";
 import { Locale } from "../../utilities/Locale.js";
 import "../field/UField.js";
-import { UOption } from "../option/UOption.js";
 import { UPopover } from "../popover/UPopover.js";
+import { UOption } from "../option/UOption.js";
 import { styles } from "./UInput.styles.js";
 import { html } from "lit";
 import { customElement, property, query, state } from "lit/decorators.js";

package/dist/components/menu-item/UMenuItem.js

@@ -2,8 +2,8 @@ import { UElement } from "../UElement.js";
 import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorateMetadata.js";
 import __decorate from "../../_virtual/_@oxc-project_runtime@0.143.0/helpers/esm/decorate.js";
 import "../icon/UIcon.js";
-import { UDivider } from "../divider/UDivider.js";
 import "../popover/UPopover.js";
+import { UDivider } from "../divider/UDivider.js";
 import { styles } from "./UMenuItem.styles.js";
 import { html } from "lit";
 import { customElement, property, state } from "lit/decorators.js";

package/dist/components/select/USelect.js

@@ -5,8 +5,8 @@ import "../spinner/USpinner.js";
 import "../icon/UIcon.js";
 import { Locale } from "../../utilities/Locale.js";
 import "../field/UField.js";
-import { UOption } from "../option/UOption.js";
 import { UPopover } from "../popover/UPopover.js";
+import { UOption } from "../option/UOption.js";
 import { styles } from "./USelect.styles.js";
 import { html } from "lit";
 import { customElement, property, query, state } from "lit/decorators.js";

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from './components/carousel/UCarousel.js';
 export * from './components/checkbox/UCheckbox.js';
 export * from './components/chip/UChip.js';
 export * from './components/copy-button/UCopyButton.js';
+export * from './components/date-picker/UDatePicker.js';
 export * from './components/dialog/UDialog.js';
 export * from './components/divider/UDivider.js';
 export * from './components/drawer/UDrawer.js';
@@ -59,6 +60,7 @@ export * from './utilities/BrowserStorage.js';
 export * from './utilities/converters.js';
 export * from './utilities/Dialog.js';
 export * from './utilities/elements.js';
+export * from './utilities/format.js';
 export * from './utilities/icons.js';
 export * from './utilities/Locale.js';
 export * from './utilities/OverlayManager.js';

package/dist/index.js

@@ -24,14 +24,16 @@ import { UCheckbox } from "./components/checkbox/UCheckbox.js";
 import { UTag } from "./components/tag/UTag.js";
 import { UChip } from "./components/chip/UChip.js";
 import { UCopyButton } from "./components/copy-button/UCopyButton.js";
+import { UField } from "./components/field/UField.js";
+import { UPopover } from "./components/popover/UPopover.js";
+import { formatCurrency, formatDate, formatNumber } from "./utilities/format.js";
+import { UDatePicker } from "./components/date-picker/UDatePicker.js";
 import { UDialog } from "./components/dialog/UDialog.js";
 import { UDivider } from "./components/divider/UDivider.js";
 import { UDrawer } from "./components/drawer/UDrawer.js";
 import { UExpander } from "./components/expander/UExpander.js";
-import { UField } from "./components/field/UField.js";
 import { UForm } from "./components/form/UForm.js";
 import { UOption } from "./components/option/UOption.js";
-import { UPopover } from "./components/popover/UPopover.js";
 import { UInput } from "./components/input/UInput.js";
 import { UMenuItem } from "./components/menu-item/UMenuItem.js";
 import { UMenu } from "./components/menu/UMenu.js";
@@ -55,4 +57,4 @@ import { BrowserStorage } from "./utilities/BrowserStorage.js";
 import { Dialog } from "./utilities/Dialog.js";
 import { Theme } from "./utilities/Theme.js";
 import { Toast } from "./utilities/Toast.js";
-export { BrowserStorage, Dialog, IconCache, IconRegistry, Locale, OverlayManager, Theme, Toast, UAlert, UAvatar, UBadge, UBreadcrumb, UBreadcrumbItem, UButton, UButtonGroup, UCard, UCarousel, UCheckbox, UChip, UCopyButton, UDialog, UDivider, UDrawer, UElement, UExpander, UField, UFloatingElement, UForm, UFormControlElement, UIcon, UIconButton, UInput, UMenu, UMenuItem, UOption, UOverlayElement, UPanel, UPopover, UProgressBar, UProgressRing, URadio, URating, USelect, USkeleton, USlider, USpinner, USplitPanel, USwitch, UTab, UTabPanel, UTag, UText, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, getDefaultBaseUrl, getParentElement, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };
+export { BrowserStorage, Dialog, IconCache, IconRegistry, Locale, OverlayManager, Theme, Toast, UAlert, UAvatar, UBadge, UBreadcrumb, UBreadcrumbItem, UButton, UButtonGroup, UCard, UCarousel, UCheckbox, UChip, UCopyButton, UDatePicker, UDialog, UDivider, UDrawer, UElement, UExpander, UField, UFloatingElement, UForm, UFormControlElement, UIcon, UIconButton, UInput, UMenu, UMenuItem, UOption, UOverlayElement, UPanel, UPopover, UProgressBar, UProgressRing, URadio, URating, USelect, USkeleton, USlider, USpinner, USplitPanel, USwitch, UTab, UTabPanel, UTag, UText, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, formatCurrency, formatDate, formatNumber, getDefaultBaseUrl, getParentElement, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };

package/dist/react/UDatePicker.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { UDatePicker as UDatePickerElement } from '../components/date-picker/UDatePicker';
+
+export declare const UDatePicker: React.ForwardRefExoticComponent<
+  Omit<Partial<UDatePickerElement>, keyof React.HTMLAttributes<UDatePickerElement>>
+    & Omit<React.HTMLAttributes<UDatePickerElement>, 'onChange'>
+    & React.RefAttributes<UDatePickerElement>
+    & {
+  onChange?: (event: CustomEvent) => void;
+  }
+>;
+
+export type UDatePickerProps = React.ComponentProps<typeof UDatePicker>;

package/dist/react/UDatePicker.js

@@ -0,0 +1,12 @@
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { UDatePicker as UDatePickerElement } from '../components/date-picker/UDatePicker.js';
+
+export const UDatePicker = createComponent({
+  react: React,
+  tagName: 'u-date-picker',
+  elementClass: UDatePickerElement,
+  events: {
+    onChange: 'change',
+  },
+});

package/dist/react/index.d.ts

@@ -30,6 +30,7 @@ export { UExpander, UExpanderProps } from './UExpander';
 export { UDrawer, UDrawerProps } from './UDrawer';
 export { UDivider, UDividerProps } from './UDivider';
 export { UDialog, UDialogProps } from './UDialog';
+export { UDatePicker, UDatePickerProps } from './UDatePicker';
 export { UCopyButton, UCopyButtonProps } from './UCopyButton';
 export { UChip, UChipProps } from './UChip';
 export { UCheckbox, UCheckboxProps } from './UCheckbox';

package/dist/react/index.js

@@ -30,6 +30,7 @@ export { UExpander } from './UExpander.js';
 export { UDrawer } from './UDrawer.js';
 export { UDivider } from './UDivider.js';
 export { UDialog } from './UDialog.js';
+export { UDatePicker } from './UDatePicker.js';
 export { UCopyButton } from './UCopyButton.js';
 export { UChip } from './UChip.js';
 export { UCheckbox } from './UCheckbox.js';

package/dist/utilities/format.d.ts

@@ -0,0 +1,25 @@
+import { LocaleTag } from './Locale.js';
+/**
+ * Wraps `Intl.NumberFormat` with the active locale (`Locale.get()` if omitted).
+ */
+export declare function formatNumber(value: number, options?: Intl.NumberFormatOptions, locale?: LocaleTag): string;
+/**
+ * Formats a number as currency. The `currency` code is **required and has no default** —
+ * the caller must always specify it (e.g. `'KRW'`, `'USD'`). Currency selection is domain knowledge,
+ * and this utility does not assume a default.
+ *
+ * @note If `options` contains `currency` or `style`, they will override the explicit `currency` argument.
+ */
+export declare function formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions, locale?: LocaleTag): string;
+/**
+ * Wraps `Intl.DateTimeFormat` with the active locale. Accepts a Date object or
+ * an ISO `YYYY-MM-DD` date string (parsed as local time, not UTC).
+ *
+ * A value that can't be resolved to a real date (malformed string, or an
+ * already-Invalid `Date`) degrades to `String(value)` rather than throwing —
+ * `Intl.DateTimeFormat.format()` throws `RangeError` on an Invalid Date, and this
+ * utility is called from render paths where an uncaught throw blanks the whole
+ * component. Same degrade-instead-of-throw contract as `formatCurrency`'s
+ * missing-`currency` fallback.
+ */
+export declare function formatDate(value: Date | string, options?: Intl.DateTimeFormatOptions, locale?: LocaleTag): string;

package/dist/utilities/format.js

@@ -0,0 +1,61 @@
+import { Locale } from "./Locale.js";
+//#region src/utilities/format.ts
+/**
+* Parses "YYYY-MM-DD" as midnight in the **local** timezone.
+* Using `Date.parse("YYYY-MM-DD")` (UTC interpretation) shifts the date
+* back a day in negative-UTC-offset regions — split y/m/d and construct
+* `new Date(y, m-1, d)` directly instead.
+*
+* A full ISO datetime (e.g. `2026-02-24T09:00:00Z`) is unambiguous — it carries
+* its own timezone — so the local-time-safe split isn't needed there; when the
+* split doesn't yield three numbers, fall back to native parsing instead of
+* producing an Invalid Date.
+*/
+function parseISODate(iso) {
+	const [y, m, d] = iso.split("-").map(Number);
+	return Number.isNaN(y) || Number.isNaN(m) || Number.isNaN(d) ? new Date(iso) : new Date(y, m - 1, d);
+}
+/**
+* Resolves a Date or ISO date string to a Date object.
+*/
+function resolve(value) {
+	return typeof value === "string" ? parseISODate(value) : value;
+}
+/**
+* Wraps `Intl.NumberFormat` with the active locale (`Locale.get()` if omitted).
+*/
+function formatNumber(value, options, locale) {
+	return new Intl.NumberFormat(locale ?? Locale.get(), options).format(value);
+}
+/**
+* Formats a number as currency. The `currency` code is **required and has no default** —
+* the caller must always specify it (e.g. `'KRW'`, `'USD'`). Currency selection is domain knowledge,
+* and this utility does not assume a default.
+*
+* @note If `options` contains `currency` or `style`, they will override the explicit `currency` argument.
+*/
+function formatCurrency(value, currency, options, locale) {
+	return new Intl.NumberFormat(locale ?? Locale.get(), {
+		style: "currency",
+		currency,
+		...options
+	}).format(value);
+}
+/**
+* Wraps `Intl.DateTimeFormat` with the active locale. Accepts a Date object or
+* an ISO `YYYY-MM-DD` date string (parsed as local time, not UTC).
+*
+* A value that can't be resolved to a real date (malformed string, or an
+* already-Invalid `Date`) degrades to `String(value)` rather than throwing —
+* `Intl.DateTimeFormat.format()` throws `RangeError` on an Invalid Date, and this
+* utility is called from render paths where an uncaught throw blanks the whole
+* component. Same degrade-instead-of-throw contract as `formatCurrency`'s
+* missing-`currency` fallback.
+*/
+function formatDate(value, options, locale) {
+	const date = resolve(value);
+	if (Number.isNaN(date.getTime())) return String(value);
+	return new Intl.DateTimeFormat(locale ?? Locale.get(), options).format(date);
+}
+//#endregion
+export { formatCurrency, formatDate, formatNumber };

package/dist/utilities/icons.js

@@ -1,6 +1,7 @@
 import alert_circle_fill_svg_default from "../_virtual/_glob-assets_raw/alert-circle-fill.svg.1e438750.js";
 import alert_triangle_fill_svg_default from "../_virtual/_glob-assets_raw/alert-triangle-fill.svg.1a8797c4.js";
 import bell_fill_svg_default from "../_virtual/_glob-assets_raw/bell-fill.svg.d37c41d9.js";
+import calendar_svg_default from "../_virtual/_glob-assets_raw/calendar.svg.02c3abd8.js";
 import check_svg_default from "../_virtual/_glob-assets_raw/check.svg.4690b01e.js";
 import chevron_down_svg_default from "../_virtual/_glob-assets_raw/chevron-down.svg.0ccd06ea.js";
 import chevron_left_svg_default from "../_virtual/_glob-assets_raw/chevron-left.svg.b4601050.js";
@@ -41,6 +42,7 @@ var InternalIconBundle = new Map(Object.entries(/* #__PURE__ */ Object.assign({
 	"../assets/icons/alert-circle-fill.svg": alert_circle_fill_svg_default,
 	"../assets/icons/alert-triangle-fill.svg": alert_triangle_fill_svg_default,
 	"../assets/icons/bell-fill.svg": bell_fill_svg_default,
+	"../assets/icons/calendar.svg": calendar_svg_default,
 	"../assets/icons/check.svg": check_svg_default,
 	"../assets/icons/chevron-down.svg": chevron_down_svg_default,
 	"../assets/icons/chevron-left.svg": chevron_left_svg_default,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "keywords": [
     "iyulab",
     "components",

package/skills/iyulab-components/references/components/date-picker.md

@@ -0,0 +1,71 @@
+# u-date-picker
+
+```ts
+import '@iyulab/components/dist/components/date-picker/UDatePicker.js';
+```
+
+**Tag:** `u-date-picker`
+
+Single-date selection with a popover calendar. The value follows the same convention as the native `input[type=date]`: an ISO `YYYY-MM-DD` string. Form-associated.
+
+> The calendar week always starts on Sunday, regardless of locale.
+
+```html
+<u-date-picker name="start-date" label="Start date"></u-date-picker>
+
+<!-- Clearable with a bounded range -->
+<u-date-picker name="due-date" label="Due date" clearable min="2026-01-01" max="2026-12-31"></u-date-picker>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `string` | — | — | Selected date (ISO `YYYY-MM-DD`) |
+| `min` | `string` | — | — | Minimum selectable date (ISO `YYYY-MM-DD`) |
+| `max` | `string` | — | — | Maximum selectable date (ISO `YYYY-MM-DD`) |
+| `clearable` | `boolean` | `false` | ✓ | Show clear button |
+| `placeholder` | `string` | — | — | Placeholder text |
+| `disabled` | `boolean` | `false` | ✓ | Disable |
+| `readonly` | `boolean` | `false` | ✓ | Read-only |
+| `required` | `boolean` | `false` | ✓ | Required |
+| `invalid` | `boolean` | `false` | ✓ | Validation failed |
+| `name` | `string` | — | — | Form field name |
+| `label` | `string` | — | — | Field label |
+| `description` | `string` | — | — | Helper text |
+| `validationMessage` | `string` | — | — | Custom validation message |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fires when the user clicks a date cell, confirms via keyboard, or clicks the clear button. Programmatic value assignment does not fire it. |
+
+## Methods
+
+| Method | Description |
+|--------|--------------|
+| `validate()` | Validate; sets `invalid` |
+| `reset()` | Reset value |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `field` | The `u-field` element |
+| `container` | The element wrapping the trigger area |
+| `popover` | The popover element showing the calendar |
+| `calendar` | The calendar container |
+| `calendar-header` | The month navigation header |
+| `calendar-title` | The "Month Year" title |
+| `calendar-weekdays` | The weekday header row |
+| `calendar-grid` | The date grid |
+| `day` | A date cell button |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--date-picker-popover-width` | Width of the calendar popover (default: 296px, independent of trigger width — a fixed-width calendar reads more naturally) |