From d8b1415f9ccd3016dc32f0127e37b237bdb179dc Mon Sep 17 00:00:00 2001
From: Truman Gao <106889354+tdgao@users.noreply.github.com>
Date: Wed, 20 May 2026 11:50:46 -0600
Subject: [PATCH] feat: swap date input to use date picker (#6146)

* feat: swap date input to use date picker

* feat: update date picker to analytics branch changes

* feat: polish date picker usage
---
 .../withdraw-stages/MuralpayDetailsStage.vue  |   4 +-
 .../withdraw-stages/MuralpayKycStage.vue      |   7 +-
 apps/frontend/src/pages/legal/cmp-info.vue    |   9 +-
 apps/frontend/src/pages/settings/pats.vue     |  26 +-
 .../ui/src/components/base/DatePicker.vue     | 689 ++++++++++++++++--
 .../ui/src/stories/base/DatePicker.stories.ts | 168 ++++-
 6 files changed, 836 insertions(+), 67 deletions(-)

diff --git a/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayDetailsStage.vue b/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayDetailsStage.vue
index eacf8c4e8..f0e4b6311 100644
--- a/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayDetailsStage.vue
+++ b/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayDetailsStage.vue
@@ -131,10 +131,9 @@
 				class="h-10"
 			/>
 
-			<StyledInput
+			<DatePicker
 				v-else-if="field.type === 'date'"
 				v-model="formData[field.name]"
-				type="date"
 				wrapper-class="w-full"
 			/>
 
@@ -230,6 +229,7 @@ import {
 	Admonition,
 	Checkbox,
 	Combobox,
+	DatePicker,
 	defineMessages,
 	financialMessages,
 	formFieldLabels,
diff --git a/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayKycStage.vue b/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayKycStage.vue
index ae2ea2787..f3d275c75 100644
--- a/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayKycStage.vue
+++ b/apps/frontend/src/components/ui/dashboard/withdraw-stages/MuralpayKycStage.vue
@@ -95,11 +95,11 @@
 							<span class="text-red">*</span>
 						</span>
 					</label>
-					<StyledInput
+					<DatePicker
 						v-model="formData.dateOfBirth"
-						type="date"
-						:max="maxDate"
+						:max-date="maxDate"
 						autocomplete="bday"
+						placeholder="Select date of birth"
 						wrapper-class="w-full"
 					/>
 				</div>
@@ -213,6 +213,7 @@
 import {
 	Chips,
 	Combobox,
+	DatePicker,
 	defineMessages,
 	formFieldLabels,
 	formFieldPlaceholders,
diff --git a/apps/frontend/src/pages/legal/cmp-info.vue b/apps/frontend/src/pages/legal/cmp-info.vue
index fff4dc340..17fab718a 100644
--- a/apps/frontend/src/pages/legal/cmp-info.vue
+++ b/apps/frontend/src/pages/legal/cmp-info.vue
@@ -102,7 +102,12 @@
 				<tr>
 					<td>Revenue earned on</td>
 					<td>
-						<StyledInput id="revenue-date-picker" v-model="rawSelectedDate" type="date" />
+						<DatePicker
+							id="revenue-date-picker"
+							v-model="rawSelectedDate"
+							show-today
+							position="above"
+						/>
 						<noscript
 							>(JavaScript must be enabled for the date picker to function, example date:
 							2024-07-15)
@@ -162,7 +167,7 @@
 </template>
 
 <script lang="ts" setup>
-import { injectModrinthClient, StyledInput, useFormatDateTime, useFormatMoney } from '@modrinth/ui'
+import { DatePicker, injectModrinthClient, useFormatDateTime, useFormatMoney } from '@modrinth/ui'
 import { useQuery } from '@tanstack/vue-query'
 import dayjs from 'dayjs'
 import { computed, ref } from 'vue'
diff --git a/apps/frontend/src/pages/settings/pats.vue b/apps/frontend/src/pages/settings/pats.vue
index 019317476..cc74abfba 100644
--- a/apps/frontend/src/pages/settings/pats.vue
+++ b/apps/frontend/src/pages/settings/pats.vue
@@ -16,10 +16,10 @@
 			"
 			:width="'550px'"
 		>
-			<div class="flex flex-col gap-4">
-				<div class="flex w-full flex-col">
+			<div class="flex flex-col gap-6">
+				<div class="flex w-full flex-col gap-2.5">
 					<label for="pat-name">
-						<span class="label__title">{{ formatMessage(createModalMessages.nameLabel) }}</span>
+						<span class="font-semibold">{{ formatMessage(createModalMessages.nameLabel) }}</span>
 					</label>
 					<StyledInput
 						id="pat-name"
@@ -29,20 +29,20 @@
 					/>
 				</div>
 
-				<div class="flex w-full flex-col">
+				<div class="flex w-full flex-col gap-2.5">
 					<label for="pat-scopes">
-						<span class="label__title">{{ formatMessage(commonMessages.scopesLabel) }}</span>
+						<span class="font-semibold">{{ formatMessage(commonMessages.scopesLabel) }}</span>
 					</label>
 					<div
 						id="pat-scopes"
-						class="scope-items mt-2 grid grid-cols-1 gap-x-6 gap-y-4 min-[600px]:grid-cols-2"
+						class="scope-items grid grid-cols-1 gap-x-6 gap-y-4 min-[600px]:grid-cols-2"
 					>
 						<div
 							v-for="category in scopeCategories"
 							:key="category.name"
-							class="flex flex-col gap-2"
+							class="flex flex-col gap-1.5"
 						>
-							<h4 class="m-0 border-b border-divider pb-1 text-base font-bold text-contrast">
+							<h4 class="m-0 border-b border-divider text-base font-medium text-primary">
 								{{ category.name }}
 							</h4>
 							<div class="flex flex-col gap-2">
@@ -58,15 +58,14 @@
 					</div>
 				</div>
 
-				<div class="flex w-full flex-col">
+				<div class="flex w-full flex-col gap-2.5">
 					<label for="pat-expires">
-						<span class="label__title">{{ formatMessage(createModalMessages.expiresLabel) }}</span>
+						<span class="font-semibold">{{ formatMessage(createModalMessages.expiresLabel) }}</span>
 					</label>
-					<StyledInput id="pat-expires" v-model="expires" type="date" />
-					<p></p>
+					<DatePicker id="pat-expires" show-today v-model="expires" wrapper-class="w-full" />
 				</div>
 
-				<div class="ml-auto flex gap-2">
+				<div class="ml-auto mt-4 flex gap-2">
 					<ButtonStyled type="outlined">
 						<button @click="$refs.patModal.hide()">
 							<XIcon />
@@ -207,6 +206,7 @@ import {
 	commonSettingsMessages,
 	ConfirmModal,
 	CopyCode,
+	DatePicker,
 	defineMessages,
 	injectModrinthClient,
 	injectNotificationManager,
diff --git a/packages/ui/src/components/base/DatePicker.vue b/packages/ui/src/components/base/DatePicker.vue
index 435459769..55b4c8292 100644
--- a/packages/ui/src/components/base/DatePicker.vue
+++ b/packages/ui/src/components/base/DatePicker.vue
@@ -1,16 +1,21 @@
 <template>
 	<div
+		ref="wrapperRef"
 		class="modrinth-date-picker relative inline-flex items-center"
 		:class="[
 			wrapperClass,
+			calendarOnly ? 'calendar-only' : '',
 			disabled ? 'cursor-not-allowed opacity-50' : '',
 			showToday ? 'show-today' : '',
+			props.mode === 'range' && selectedDates.length < 2 ? 'can-select-range' : '',
+			props.mode === 'range' && selectedDates.length === 1 ? 'is-selecting-range' : '',
 			props.mode === 'range' && selectedDates.length === 2 ? 'can-drag-range' : '',
 			rangeDragState ? 'is-dragging-range' : '',
+			rangeEndpointMoveState ? 'is-moving-range-end' : '',
 		]"
 	>
 		<CalendarIcon
-			v-if="showIcon"
+			v-if="showIcon && !calendarOnly"
 			class="pointer-events-none absolute left-3 z-[1] h-5 w-5 text-secondary opacity-60 transition-colors"
 			aria-hidden="true"
 		/>
@@ -23,6 +28,8 @@
 			:readonly="readonly"
 			:autocomplete="autocomplete"
 			:class="inputClasses"
+			:tabindex="calendarOnly ? -1 : undefined"
+			:aria-hidden="calendarOnly ? 'true' : undefined"
 			type="text"
 		/>
 	</div>
@@ -41,6 +48,21 @@ import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 
 type DatePickerValue = string | Date | null | undefined
 type RangeEdge = 'start' | 'end'
+type ViewDateAlignment = 'left' | 'right'
+type DatePickerPosition =
+	| 'auto'
+	| 'above'
+	| 'below'
+	| 'auto left'
+	| 'auto center'
+	| 'auto right'
+	| 'above left'
+	| 'above center'
+	| 'above right'
+	| 'below left'
+	| 'below center'
+	| 'below right'
+type CalendarViewMonth = { month: number; year: number }
 type RangeDayElement = HTMLElement & { dateObj?: Date }
 type RangeDragState = {
 	edge: RangeEdge
@@ -48,6 +70,13 @@ type RangeDragState = {
 	draggedEndpointDate: Date
 	pointerId: number
 	lastDateTime: number
+	hasMoved: boolean
+}
+type RangeEndpointMoveState = {
+	edge: RangeEdge
+	anchorDate: Date
+	endpointDate: Date
+	lastPreviewDateTime: number
 }
 
 const model = defineModel<DatePickerValue | DatePickerValue[]>()
@@ -71,6 +100,12 @@ const props = withDefaults(
 		 * first opens (and on subsequent opens while the value is empty).
 		 */
 		defaultViewDate?: string | Date
+		/**
+		 * Controls which visible calendar contains the opening view date when
+		 * multiple months are shown. In range mode, a complete range opens to
+		 * the end date.
+		 */
+		viewDateAlignment?: ViewDateAlignment
 		/**
 		 * The stored value format emitted by v-model. See https://flatpickr.js.org/formatting/
 		 *
@@ -91,6 +126,12 @@ const props = withDefaults(
 		clearable?: boolean
 		showIcon?: boolean
 		showToday?: boolean
+		calendarOnly?: boolean
+		/**
+		 * Controls where the calendar opens relative to the input. Use `above`
+		 * to force the calendar to open above the input.
+		 */
+		position?: DatePickerPosition
 		/**
 		 * When true (single mode only), navigating between months/years preserves the
 		 * originally selected day number. If the target month has fewer days, the day
@@ -101,6 +142,7 @@ const props = withDefaults(
 		preserveDay?: boolean
 		wrapperClass?: string
 		inputClass?: string
+		calendarClass?: string
 	}>(),
 	{
 		disabled: false,
@@ -110,9 +152,13 @@ const props = withDefaults(
 		showMonths: 1,
 		time24hr: false,
 		clearable: true,
+		placeholder: 'Enter date',
 		showIcon: true,
 		showToday: false,
+		calendarOnly: false,
+		position: 'auto',
 		preserveDay: false,
+		viewDateAlignment: 'left',
 	},
 )
 
@@ -123,14 +169,84 @@ const emit = defineEmits<{
 }>()
 
 const inputRef = ref<HTMLInputElement>()
+const wrapperRef = ref<HTMLElement>()
 const picker = ref<Instance>()
 const isSyncingFromModel = ref(false)
-const intendedViewMonth = ref<{ month: number; year: number } | null>(null)
+const intendedViewMonth = ref<CalendarViewMonth | null>(null)
+const preserveViewOnNextModelSync = ref(false)
 const intendedDay = ref<number | null>(null)
 const isPreservingDay = ref(false)
 const rangeDragState = ref<RangeDragState | null>(null)
+const rangeEndpointMoveState = ref<RangeEndpointMoveState | null>(null)
 const suppressNextRangeClick = ref(false)
 let rangeClickSuppressionTimeout: number | null = null
+let monthSelectSyncFrame: number | null = null
+let calendarPortal: HTMLElement | null = null
+const calendarBaseClass = 'modrinth-date-picker-calendar'
+const calendarStateClasses = [
+	'calendar-only',
+	'show-today',
+	'can-select-range',
+	'is-selecting-range',
+	'can-drag-range',
+	'is-dragging-range',
+	'is-moving-range-end',
+]
+
+function getCalendarStateClasses() {
+	return [
+		props.calendarOnly ? 'calendar-only' : '',
+		props.showToday ? 'show-today' : '',
+		props.mode === 'range' && selectedDates.value.length < 2 ? 'can-select-range' : '',
+		props.mode === 'range' && selectedDates.value.length === 1 ? 'is-selecting-range' : '',
+		props.mode === 'range' && selectedDates.value.length === 2 ? 'can-drag-range' : '',
+		rangeDragState.value ? 'is-dragging-range' : '',
+		rangeEndpointMoveState.value ? 'is-moving-range-end' : '',
+	].filter(Boolean)
+}
+
+function syncCalendarStateClasses(instance?: Instance) {
+	const container = (instance ?? picker.value)?.calendarContainer
+	const targets = [container, calendarPortal].filter((target): target is HTMLElement =>
+		Boolean(target),
+	)
+	if (targets.length === 0) return
+
+	for (const target of targets) {
+		for (const cls of calendarStateClasses) {
+			target.classList.remove(cls)
+		}
+
+		for (const cls of getCalendarStateClasses()) {
+			target.classList.add(cls)
+		}
+	}
+}
+
+function ensureCalendarPortal() {
+	if (props.calendarOnly || typeof document === 'undefined') return undefined
+
+	if (!calendarPortal) {
+		calendarPortal = document.createElement('div')
+		calendarPortal.classList.add('modrinth-date-picker', 'modrinth-date-picker-portal')
+
+		for (const attr of wrapperRef.value?.getAttributeNames() ?? []) {
+			if (attr.startsWith('data-v-')) {
+				calendarPortal.setAttribute(attr, '')
+			}
+		}
+
+		document.body.appendChild(calendarPortal)
+	}
+
+	syncCalendarStateClasses()
+	return calendarPortal
+}
+
+function destroyCalendarPortal() {
+	calendarPortal?.remove()
+	calendarPortal = null
+}
 
 function getDayFromDateStr(dateStr: string): number | null {
 	const parts = dateStr.split('-')
@@ -171,6 +287,32 @@ function applyPreserveDay(instance: Instance) {
 	})
 }
 
+let appliedCalendarClasses: string[] = []
+
+function parseClassString(value: string | undefined): string[] {
+	if (!value) return []
+	return value.split(/\s+/).filter(Boolean)
+}
+
+function syncCalendarClasses(instance?: Instance) {
+	const container = (instance ?? picker.value)?.calendarContainer
+	if (!container) return
+
+	container.classList.add(calendarBaseClass)
+
+	for (const cls of appliedCalendarClasses) {
+		container.classList.remove(cls)
+	}
+
+	const nextClasses = parseClassString(props.calendarClass)
+	for (const cls of nextClasses) {
+		container.classList.add(cls)
+	}
+
+	appliedCalendarClasses = nextClasses
+	syncCalendarStateClasses(instance)
+}
+
 function syncHeaderControlState(instance: Instance) {
 	const prevDisabled = instance.prevMonthNav.classList.contains('flatpickr-disabled')
 	const nextDisabled = instance.nextMonthNav.classList.contains('flatpickr-disabled')
@@ -185,6 +327,166 @@ function syncHeaderControlState(instance: Instance) {
 	}
 }
 
+function getDisplayedMonthDate(instance: Instance, index: number) {
+	return new Date(instance.currentYear, instance.currentMonth + index, 1)
+}
+
+function getMonthName(instance: Instance, month: number) {
+	const monthNames = instance.config.shorthandCurrentMonth
+		? instance.l10n.months.shorthand
+		: instance.l10n.months.longhand
+	return monthNames[month] ?? ''
+}
+
+function syncMultiMonthSelects(instance = picker.value) {
+	if (!instance) return
+
+	for (const select of instance.monthNav.querySelectorAll('.modrinth-monthDropdown-months')) {
+		select.remove()
+	}
+
+	for (const monthElement of instance.monthNav.querySelectorAll('.modrinth-hidden-cur-month')) {
+		monthElement.classList.remove('modrinth-hidden-cur-month')
+	}
+
+	const showMultiMonthSelects =
+		resolvedShowMonths.value >= 1 && !instance.isMobile && !instance.config.noCalendar
+	instance.calendarContainer.classList.toggle('has-multi-month-selects', showMultiMonthSelects)
+	if (!showMultiMonthSelects) return
+
+	instance.monthElements.forEach((monthElement, index) => {
+		const currentMonth = monthElement.closest('.flatpickr-current-month')
+		if (!currentMonth) return
+
+		const displayedMonthDate = getDisplayedMonthDate(instance, index)
+		const displayedYear = displayedMonthDate.getFullYear()
+		const displayedMonth = displayedMonthDate.getMonth()
+		const monthSelect = document.createElement('select')
+		monthSelect.className = 'flatpickr-monthDropdown-months modrinth-monthDropdown-months'
+		monthSelect.setAttribute('aria-label', instance.l10n.monthAriaLabel)
+		monthSelect.tabIndex = -1
+
+		for (let month = 0; month < 12; month++) {
+			const option = document.createElement('option')
+			option.className = 'flatpickr-monthDropdown-month'
+			option.value = String(month)
+			option.textContent = getMonthName(instance, month)
+			option.selected = month === displayedMonth
+			monthSelect.appendChild(option)
+		}
+
+		monthSelect.addEventListener('change', () => {
+			const selectedMonth = Number.parseInt(monthSelect.value, 10)
+			const selectedYear = Number.parseInt(
+				instance.yearElements[index]?.value ?? String(displayedYear),
+				10,
+			)
+			if (!Number.isFinite(selectedMonth) || !Number.isFinite(selectedYear)) return
+
+			instance.jumpToDate(new Date(selectedYear, selectedMonth - index, 1), true)
+			syncHeaderControlState(instance)
+			syncMissingRangeEndState()
+			syncRangeEndpointMoveState(instance)
+			syncMultiMonthSelects(instance)
+		})
+
+		monthElement.classList.add('modrinth-hidden-cur-month')
+		currentMonth.insertBefore(monthSelect, monthElement)
+	})
+}
+
+function changeYearInput(instance: Instance, input: HTMLInputElement, delta: number) {
+	const index = instance.yearElements.indexOf(input)
+	if (index < 0) return
+
+	const displayedMonthDate = getDisplayedMonthDate(instance, index)
+	const displayedYear = displayedMonthDate.getFullYear()
+	const selectedYear = Number.parseInt(input.value, 10)
+	const nextYear = (Number.isFinite(selectedYear) ? selectedYear : displayedYear) + delta
+
+	instance.jumpToDate(new Date(nextYear, displayedMonthDate.getMonth() - index, 1), true)
+	syncHeaderControlState(instance)
+	syncMissingRangeEndState()
+	syncRangeEndpointMoveState(instance)
+	syncMultiMonthSelects(instance)
+}
+
+function queueMultiMonthSelectSync(instance: Instance) {
+	if (monthSelectSyncFrame !== null) window.cancelAnimationFrame(monthSelectSyncFrame)
+
+	monthSelectSyncFrame = window.requestAnimationFrame(() => {
+		monthSelectSyncFrame = null
+		syncMultiMonthSelects(instance)
+	})
+}
+
+function parseViewDate(value: DatePickerValue, instance: Instance): Date | null {
+	if (!value) return null
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+
+	const parsedDate =
+		instance.parseDate(value, resolvedDateFormat.value) ?? instance.parseDate(value)
+	if (parsedDate && !Number.isNaN(parsedDate.getTime())) return parsedDate
+
+	const nativeDate = new Date(value)
+	return Number.isNaN(nativeDate.getTime()) ? null : nativeDate
+}
+
+function getAlignedViewDate(date: Date) {
+	if (props.viewDateAlignment !== 'right') return date
+
+	const calendarOffset = resolvedShowMonths.value - 1
+	if (calendarOffset <= 0) return date
+
+	return new Date(date.getFullYear(), date.getMonth() - calendarOffset, 1)
+}
+
+function getOpeningViewDate() {
+	if (props.mode === 'range' && selectedDates.value.length >= 2) {
+		return selectedDates.value[selectedDates.value.length - 1] ?? null
+	}
+
+	return selectedDates.value[0] ?? props.defaultViewDate ?? null
+}
+
+function hasCompleteRange(instance: Instance) {
+	return props.mode === 'range' && instance.selectedDates.length === 2
+}
+
+function hasCompleteModelRange() {
+	return props.mode === 'range' && selectedDates.value.length === 2
+}
+
+function getCompleteRangeInputValue(instance: Instance, format: string) {
+	if (!hasCompleteRange(instance)) return null
+
+	const rangeValues = instance.selectedDates.map((date) => instance.formatDate(date, format))
+	if (rangeValues[0] === rangeValues[1]) return rangeValues[0] ?? null
+
+	return rangeValues.join(instance.l10n.rangeSeparator)
+}
+
+function syncInputDisplayValue(instance = picker.value) {
+	if (!instance) return
+
+	const inputValue = getCompleteRangeInputValue(instance, resolvedDateFormat.value)
+	if (inputValue) {
+		instance.input.value = inputValue
+	}
+
+	const altInputValue = getCompleteRangeInputValue(instance, resolvedAltFormat.value)
+	if (instance.altInput && altInputValue) {
+		instance.altInput.value = altInputValue
+	}
+}
+
+function syncCalendarView(instance: Instance) {
+	const viewDate = parseViewDate(getOpeningViewDate(), instance)
+	if (!viewDate) return
+
+	instance.jumpToDate(getAlignedViewDate(viewDate))
+}
+
 function getRangeDayElement(target: EventTarget | null): RangeDayElement | null {
 	if (!(target instanceof Element)) return null
 	return target.closest<RangeDayElement>('.flatpickr-day')
@@ -219,6 +521,12 @@ function dateOnlyTime(date: Date) {
 	return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime()
 }
 
+function jumpToViewMonth(instance: Instance, viewMonth: CalendarViewMonth) {
+	if (instance.currentMonth === viewMonth.month && instance.currentYear === viewMonth.year) return
+
+	instance.jumpToDate(new Date(viewMonth.year, viewMonth.month, 1))
+}
+
 function withEndpointTime(date: Date, endpoint: Date) {
 	return new Date(
 		date.getFullYear(),
@@ -231,6 +539,120 @@ function withEndpointTime(date: Date, endpoint: Date) {
 	)
 }
 
+function resolveRangeEndpointMove(targetDate: Date, endpointDate: Date, anchorDate: Date) {
+	const movedDate = withEndpointTime(targetDate, endpointDate)
+	const [nextStartDate, nextEndDate] =
+		dateOnlyTime(movedDate) <= dateOnlyTime(anchorDate)
+			? [movedDate, anchorDate]
+			: [anchorDate, movedDate]
+
+	return {
+		nextStartDate,
+		nextEndDate,
+		nextEndpointDate: movedDate,
+	}
+}
+
+function withPreservedCalendarView(instance: Instance, callback: () => void) {
+	const currentViewMonth = {
+		month: instance.currentMonth,
+		year: instance.currentYear,
+	}
+
+	callback()
+	jumpToViewMonth(instance, currentViewMonth)
+}
+
+function syncRangeEndpointMoveState(instance = picker.value) {
+	if (!instance) return
+
+	for (const dayElem of instance.calendarContainer.querySelectorAll('.is-moving-range-end')) {
+		dayElem.classList.remove('is-moving-range-end')
+	}
+
+	const state = rangeEndpointMoveState.value
+	if (!state || props.mode !== 'range' || instance.selectedDates.length !== 2) return
+
+	const selector =
+		state.edge === 'start'
+			? '.flatpickr-day.startRange:not(.endRange)'
+			: '.flatpickr-day.endRange:not(.startRange)'
+	instance.calendarContainer.querySelector(selector)?.classList.add('is-moving-range-end')
+}
+
+function setRangeEndpointMoveState(state: RangeEndpointMoveState | null) {
+	rangeEndpointMoveState.value = state
+	syncCalendarStateClasses()
+	syncRangeEndpointMoveState()
+}
+
+function selectRangeEndpointForMove(edge: RangeEdge, startDate: Date, endDate: Date) {
+	setRangeEndpointMoveState({
+		edge,
+		anchorDate: new Date(edge === 'start' ? endDate : startDate),
+		endpointDate: new Date(edge === 'start' ? startDate : endDate),
+		lastPreviewDateTime: dateTime(edge === 'start' ? startDate : endDate),
+	})
+}
+
+function cancelRangeEndpointMovePreview() {
+	if (!rangeEndpointMoveState.value) return
+
+	setRangeEndpointMoveState(null)
+	syncPickerFromModel()
+}
+
+function previewSelectedRangeEndpoint(event: MouseEvent) {
+	const state = rangeEndpointMoveState.value
+	const instance = picker.value
+	if (!state || !instance) return
+
+	const dayElem = getRangeDayElement(event.target)
+	if (!dayElem || !instance.calendarContainer.contains(dayElem) || !isSelectableDay(dayElem)) return
+
+	const { nextStartDate, nextEndDate, nextEndpointDate } = resolveRangeEndpointMove(
+		dayElem.dateObj!,
+		state.endpointDate,
+		state.anchorDate,
+	)
+	const nextPreviewDateTime = dateTime(nextEndpointDate)
+	if (nextPreviewDateTime === state.lastPreviewDateTime) return
+
+	state.lastPreviewDateTime = nextPreviewDateTime
+	withPreservedCalendarView(instance, () => {
+		instance.setDate([nextStartDate, nextEndDate], false)
+	})
+	syncHeaderControlState(instance)
+	syncMissingRangeEndState()
+	syncRangeEndpointMoveState(instance)
+}
+
+function moveSelectedRangeEndpoint(dayElem: RangeDayElement) {
+	const state = rangeEndpointMoveState.value
+	const instance = picker.value
+	if (!state || !instance || !dayElem.dateObj) return false
+
+	const { nextStartDate, nextEndDate, nextEndpointDate } = resolveRangeEndpointMove(
+		dayElem.dateObj,
+		state.endpointDate,
+		state.anchorDate,
+	)
+
+	setRangeEndpointMoveState(null)
+
+	if (dateTime(nextEndpointDate) === dateTime(state.endpointDate)) return true
+
+	intendedViewMonth.value = {
+		month: instance.currentMonth,
+		year: instance.currentYear,
+	}
+
+	instance.setDate([nextStartDate, nextEndDate], true)
+	syncHeaderControlState(instance)
+
+	return true
+}
+
 function clearRangeClickSuppressionTimeout() {
 	if (rangeClickSuppressionTimeout === null) return
 
@@ -248,6 +670,7 @@ function clearRangeClickSuppressionSoon() {
 
 function startRangeDrag(event: PointerEvent) {
 	if (event.button !== 0) return
+	if (rangeEndpointMoveState.value) return
 
 	const instance = picker.value
 	const dayElem = getRangeDayElement(event.target)
@@ -266,7 +689,9 @@ function startRangeDrag(event: PointerEvent) {
 		draggedEndpointDate,
 		pointerId: event.pointerId,
 		lastDateTime: dateTime(draggedEndpointDate),
+		hasMoved: false,
 	}
+	syncCalendarStateClasses(instance)
 	clearRangeClickSuppressionTimeout()
 	suppressNextRangeClick.value = true
 
@@ -287,17 +712,13 @@ function updateRangeDrag(event: PointerEvent) {
 	const dayElem = getRangeDayElement(target)
 	if (!dayElem || !instance.calendarContainer.contains(dayElem) || !isSelectableDay(dayElem)) return
 
-	const draggedDate = withEndpointTime(dayElem.dateObj!, state.draggedEndpointDate)
-	let nextStartDate = state.edge === 'start' ? draggedDate : state.anchorDate
-	let nextEndDate = state.edge === 'end' ? draggedDate : state.anchorDate
+	const { nextStartDate, nextEndDate, nextEndpointDate } = resolveRangeEndpointMove(
+		dayElem.dateObj!,
+		state.draggedEndpointDate,
+		state.anchorDate,
+	)
 
-	if (state.edge === 'start' && dateOnlyTime(nextStartDate) > dateOnlyTime(state.anchorDate)) {
-		nextStartDate = state.anchorDate
-	} else if (state.edge === 'end' && dateOnlyTime(nextEndDate) < dateOnlyTime(state.anchorDate)) {
-		nextEndDate = state.anchorDate
-	}
-
-	const nextDraggedTime = dateTime(state.edge === 'start' ? nextStartDate : nextEndDate)
+	const nextDraggedTime = dateTime(nextEndpointDate)
 	if (nextDraggedTime === state.lastDateTime) return
 
 	intendedViewMonth.value = {
@@ -306,6 +727,7 @@ function updateRangeDrag(event: PointerEvent) {
 	}
 
 	state.lastDateTime = nextDraggedTime
+	state.hasMoved = true
 	instance.setDate([nextStartDate, nextEndDate], true)
 	syncHeaderControlState(instance)
 
@@ -319,10 +741,20 @@ function stopRangeDrag(event: PointerEvent) {
 
 	const instance = picker.value
 	rangeDragState.value = null
+	syncCalendarStateClasses(instance)
 	document.removeEventListener('pointermove', updateRangeDrag, true)
 	document.removeEventListener('pointerup', stopRangeDrag, true)
 	document.removeEventListener('pointercancel', stopRangeDrag, true)
 	clearRangeClickSuppressionSoon()
+	if (state.hasMoved) {
+		setRangeEndpointMoveState(null)
+	} else {
+		selectRangeEndpointForMove(
+			state.edge,
+			state.edge === 'start' ? state.draggedEndpointDate : state.anchorDate,
+			state.edge === 'end' ? state.draggedEndpointDate : state.anchorDate,
+		)
+	}
 
 	if (
 		document.activeElement instanceof HTMLElement &&
@@ -336,7 +768,11 @@ function stopRangeDrag(event: PointerEvent) {
 }
 
 function stopRangeEndpointMouseEvent(event: MouseEvent) {
-	if (rangeDragState.value || suppressNextRangeClick.value) {
+	if (
+		rangeDragState.value ||
+		suppressNextRangeClick.value ||
+		(rangeEndpointMoveState.value && getRangeDayElement(event.target))
+	) {
 		event.preventDefault()
 		event.stopImmediatePropagation()
 	}
@@ -351,6 +787,37 @@ function suppressRangeDragClick(event: MouseEvent) {
 	event.stopImmediatePropagation()
 }
 
+function handleRangeEndpointMoveClick(event: MouseEvent) {
+	if (suppressNextRangeClick.value) {
+		suppressRangeDragClick(event)
+		return
+	}
+
+	const instance = picker.value
+	const dayElem = getRangeDayElement(event.target)
+	if (!instance || !dayElem || props.mode !== 'range') return
+
+	const moveState = rangeEndpointMoveState.value
+	if (moveState) {
+		if (!isSelectableDay(dayElem)) return
+
+		moveSelectedRangeEndpoint(dayElem)
+		event.preventDefault()
+		event.stopImmediatePropagation()
+		return
+	}
+
+	const edge = getRangeEdge(dayElem)
+	if (!edge) return
+
+	const [startDate, endDate] = instance.selectedDates
+	if (!startDate || !endDate) return
+
+	selectRangeEndpointForMove(edge, startDate, endDate)
+	event.preventDefault()
+	event.stopImmediatePropagation()
+}
+
 function hasRangeEnd(instance: Instance) {
 	return (
 		instance.selectedDates.length === 2 ||
@@ -360,12 +827,16 @@ function hasRangeEnd(instance: Instance) {
 
 function shouldSuppressMissingRangeEndBackground(instance?: Instance) {
 	if (props.mode !== 'range' || !instance) return false
+	if (instance.selectedDates.length !== 1) return false
 
 	const hasRangeStart = Boolean(
 		instance.calendarContainer.querySelector('.flatpickr-day.startRange:not(.endRange)'),
 	)
+	const hasRangePreview = Boolean(
+		instance.calendarContainer.querySelector('.flatpickr-day.inRange'),
+	)
 
-	return hasRangeStart && !hasRangeEnd(instance)
+	return hasRangeStart && !hasRangeEnd(instance) && !hasRangePreview
 }
 
 function syncMissingRangeEndState() {
@@ -474,10 +945,15 @@ const resolvedShowMonths = computed(() =>
 )
 
 const inputClasses = computed(() => [
-	'w-full text-primary placeholder:text-secondary focus:text-contrast font-medium transition-[shadow,color] appearance-none shadow-none focus:ring-4 focus:ring-brand-shadow !outline-0',
-	props.showIcon ? 'pl-10' : 'pl-3',
-	'pr-3 h-9 py-2 text-base outline-none bg-surface-4 border-none rounded-xl',
-	props.disabled ? 'cursor-not-allowed' : '',
+	props.calendarOnly
+		? 'sr-only pointer-events-none absolute h-0 w-0 opacity-0'
+		: 'w-full text-primary placeholder:text-secondary focus:text-contrast font-medium transition-[shadow,color] appearance-none shadow-none focus:ring-4 focus:ring-brand-shadow !outline-0',
+	!props.calendarOnly && props.showIcon ? 'pl-10' : '',
+	!props.calendarOnly && !props.showIcon ? 'pl-3' : '',
+	!props.calendarOnly
+		? 'pr-3 h-9 py-2 text-base outline-none bg-surface-4 border-none rounded-xl'
+		: '',
+	props.disabled && !props.calendarOnly ? 'cursor-not-allowed' : '',
 	props.inputClass,
 ])
 
@@ -500,9 +976,13 @@ watch(
 		props.enableTime,
 		props.mode,
 		props.showMonths,
+		props.defaultViewDate,
+		props.viewDateAlignment,
 		props.dateFormat,
 		props.altFormat,
 		props.time24hr,
+		props.calendarOnly,
+		props.position,
 	],
 	() => {
 		if (!picker.value) return
@@ -529,11 +1009,30 @@ watch(
 
 		syncAltInputState()
 		syncTimeInputTypes(picker.value)
+		if (props.mode !== 'range' || selectedDates.value.length !== 2) cancelRangeEndpointMovePreview()
 		syncPickerFromModel()
+		syncCalendarClasses()
 	},
 	{ deep: true },
 )
 
+watch(
+	() => props.calendarClass,
+	() => syncCalendarClasses(),
+)
+
+watch(
+	() => [
+		props.showToday,
+		props.calendarOnly,
+		props.mode,
+		selectedDates.value.length,
+		Boolean(rangeDragState.value),
+		Boolean(rangeEndpointMoveState.value),
+	],
+	() => syncCalendarStateClasses(),
+)
+
 onMounted(async () => {
 	await nextTick()
 	if (!inputRef.value) return
@@ -541,14 +1040,13 @@ onMounted(async () => {
 	picker.value = flatpickr(inputRef.value, {
 		...flatpickrOptions(),
 		onReady: (_selectedDates, _dateStr, instance) => {
-			if (props.defaultViewDate && instance.selectedDates.length === 0) {
-				instance.jumpToDate(props.defaultViewDate)
-			}
+			syncCalendarView(instance)
 
 			instance.calendarContainer.addEventListener('pointerdown', startRangeDrag, true)
 			instance.calendarContainer.addEventListener('mousedown', stopRangeEndpointMouseEvent, true)
 			instance.calendarContainer.addEventListener('mouseup', stopRangeEndpointMouseEvent, true)
-			instance.calendarContainer.addEventListener('click', suppressRangeDragClick, true)
+			instance.calendarContainer.addEventListener('click', handleRangeEndpointMoveClick, true)
+			instance.calendarContainer.addEventListener('mouseover', previewSelectedRangeEndpoint, true)
 			instance.calendarContainer.addEventListener('mouseover', syncMissingRangeEndState)
 			instance.calendarContainer.addEventListener('mouseleave', syncMissingRangeEndState)
 			instance.calendarContainer.addEventListener(
@@ -591,6 +1089,12 @@ onMounted(async () => {
 				(event) => {
 					const target = event.target as HTMLElement | null
 					if (!target?.matches('input.cur-year')) return
+					if (event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+						event.preventDefault()
+						event.stopImmediatePropagation()
+						changeYearInput(instance, target as HTMLInputElement, event.key === 'ArrowUp' ? 1 : -1)
+						return
+					}
 					if (
 						event.key === 'ArrowLeft' ||
 						event.key === 'ArrowRight' ||
@@ -602,9 +1106,19 @@ onMounted(async () => {
 				},
 				true,
 			)
+			instance.calendarContainer.addEventListener('keyup', (event) => {
+				const target = event.target as HTMLElement | null
+				if (!target?.matches('input.cur-year') || event.key !== 'Enter') return
+
+				window.requestAnimationFrame(() => target.blur())
+			})
 
 			syncTimeInputTypes(instance)
 			syncHeaderControlState(instance)
+			syncCalendarClasses(instance)
+			syncCalendarStateClasses(instance)
+			syncRangeEndpointMoveState(instance)
+			syncMultiMonthSelects(instance)
 		},
 		onChange: (_selectedDates, dateStr, instance) => {
 			if (isSyncingFromModel.value) return
@@ -613,22 +1127,31 @@ onMounted(async () => {
 				props.mode === 'single'
 					? dateStr || null
 					: _selectedDates.map((date) => instance.formatDate(date, resolvedDateFormat.value))
+			if (intendedViewMonth.value !== null) {
+				preserveViewOnNextModelSync.value = true
+			}
 			model.value = nextValue
 			emit('change', nextValue)
 
 			if (intendedViewMonth.value !== null) {
-				const monthDelta =
-					intendedViewMonth.value.month -
-					instance.currentMonth +
-					(intendedViewMonth.value.year - instance.currentYear) * 12
-				if (monthDelta !== 0) instance.changeMonth(monthDelta)
+				jumpToViewMonth(instance, intendedViewMonth.value)
 			}
 
 			syncHeaderControlState(instance)
 			syncMissingRangeEndState()
+			syncCalendarStateClasses(instance)
+			syncRangeEndpointMoveState(instance)
+			syncInputDisplayValue(instance)
 		},
 		onClose: (_selectedDates, dateStr, instance) => {
-			if (!props.clearable || dateStr) return
+			cancelRangeEndpointMovePreview()
+			if (hasCompleteModelRange()) {
+				syncPickerFromModel()
+				return
+			}
+
+			syncInputDisplayValue(instance)
+			if (!props.clearable || dateStr || hasCompleteRange(instance)) return
 
 			const nextValue = props.mode === 'single' ? null : []
 			model.value = nextValue
@@ -640,19 +1163,26 @@ onMounted(async () => {
 			applyPreserveDay(instance)
 			syncHeaderControlState(instance)
 			syncMissingRangeEndState()
+			syncCalendarStateClasses(instance)
+			syncRangeEndpointMoveState(instance)
+			queueMultiMonthSelectSync(instance)
 		},
 		onYearChange: (_selectedDates, _dateStr, instance) => {
 			applyPreserveDay(instance)
 			syncHeaderControlState(instance)
 			syncMissingRangeEndState()
+			syncCalendarStateClasses(instance)
+			syncRangeEndpointMoveState(instance)
+			queueMultiMonthSelectSync(instance)
 		},
 		onOpen: (_selectedDates, _dateStr, instance) => {
-			if (props.defaultViewDate && instance.selectedDates.length === 0) {
-				instance.jumpToDate(props.defaultViewDate)
-			}
+			syncCalendarView(instance)
 			syncTimeInputTypes(instance)
 			syncHeaderControlState(instance)
 			syncMissingRangeEndState()
+			syncCalendarStateClasses(instance)
+			syncRangeEndpointMoveState(instance)
+			syncMultiMonthSelects(instance)
 		},
 	})
 
@@ -664,35 +1194,41 @@ onMounted(async () => {
 	syncAltInputState()
 	syncPickerFromModel()
 	syncHeaderControlState(picker.value)
+	syncRangeEndpointMoveState(picker.value)
+	syncMultiMonthSelects(picker.value)
 })
 
 onBeforeUnmount(() => {
 	clearRangeClickSuppressionTimeout()
+	if (monthSelectSyncFrame !== null) window.cancelAnimationFrame(monthSelectSyncFrame)
 	document.removeEventListener('pointermove', updateRangeDrag, true)
 	document.removeEventListener('pointerup', stopRangeDrag, true)
 	document.removeEventListener('pointercancel', stopRangeDrag, true)
 	picker.value?.destroy()
+	destroyCalendarPortal()
 })
 
 function flatpickrOptions(): Options {
 	return {
-		allowInput: true,
-		altInput: true,
-		altInputClass: inputClasses.value.filter(Boolean).join(' '),
+		allowInput: !props.calendarOnly,
+		altInput: !props.calendarOnly,
+		altInputClass: props.calendarOnly ? undefined : inputClasses.value.filter(Boolean).join(' '),
 		altFormat: resolvedAltFormat.value,
-		appendTo: inputRef.value?.parentElement ?? undefined,
+		appendTo: ensureCalendarPortal(),
 		closeOnSelect: false,
 		dateFormat: resolvedDateFormat.value,
 		disableMobile: true,
 		enableTime: props.enableTime,
+		inline: props.calendarOnly,
 		maxDate: props.maxDate,
 		minDate: props.minDate,
 		mode: props.mode,
 		noCalendar: false,
 		nextArrow: chevronRightIcon,
+		position: props.position,
 		prevArrow: chevronLeftIcon,
 		showMonths: resolvedShowMonths.value,
-		static: true,
+		static: false,
 		time_24hr: props.time24hr,
 	}
 }
@@ -700,22 +1236,34 @@ function flatpickrOptions(): Options {
 function syncPickerFromModel() {
 	if (!picker.value) return
 
+	const preservedViewMonth =
+		intendedViewMonth.value ??
+		(preserveViewOnNextModelSync.value
+			? {
+					month: picker.value.currentMonth,
+					year: picker.value.currentYear,
+				}
+			: null)
+
 	isSyncingFromModel.value = true
 	picker.value.setDate(selectedDates.value, false, resolvedDateFormat.value)
 	syncTimeInputTypes(picker.value)
 
-	if (intendedViewMonth.value !== null) {
-		const monthDelta =
-			intendedViewMonth.value.month -
-			picker.value.currentMonth +
-			(intendedViewMonth.value.year - picker.value.currentYear) * 12
-		if (monthDelta !== 0) picker.value.changeMonth(monthDelta)
+	if (preservedViewMonth !== null) {
+		jumpToViewMonth(picker.value, preservedViewMonth)
 		intendedViewMonth.value = null
+		preserveViewOnNextModelSync.value = false
+	} else {
+		syncCalendarView(picker.value)
 	}
 
 	isSyncingFromModel.value = false
 	syncHeaderControlState(picker.value)
+	syncInputDisplayValue()
 	syncMissingRangeEndState()
+	syncCalendarStateClasses()
+	syncRangeEndpointMoveState()
+	syncMultiMonthSelects()
 }
 
 function syncAltInputState() {
@@ -733,6 +1281,7 @@ defineExpose({
 		const nextValue = props.mode === 'single' ? null : []
 		model.value = nextValue
 		picker.value?.clear(false)
+		setRangeEndpointMoveState(null)
 		syncMissingRangeEndState()
 		emit('clear')
 		emit('change', nextValue)
@@ -746,7 +1295,24 @@ defineExpose({
 }
 
 .modrinth-date-picker :deep(.flatpickr-calendar) {
-	@apply mt-2 overflow-hidden rounded-[14px] border border-solid border-surface-5 bg-surface-3 shadow-none p-3 text-primary select-none;
+	@apply mt-2 rounded-2xl border border-solid border-surface-5 bg-surface-3 shadow-none p-3 text-primary select-none;
+	box-sizing: content-box;
+}
+
+.modrinth-date-picker :deep(.flatpickr-calendar.arrowBottom) {
+	margin-top: -2.5rem;
+}
+
+.modrinth-date-picker.calendar-only {
+	@apply block;
+}
+
+.modrinth-date-picker.calendar-only :deep(.flatpickr-wrapper) {
+	@apply block w-full;
+}
+
+.modrinth-date-picker.calendar-only :deep(.flatpickr-calendar) {
+	@apply m-0;
 	box-sizing: content-box;
 }
 
@@ -801,6 +1367,9 @@ defineExpose({
 	background-repeat: no-repeat;
 	background-size: 16px 16px;
 }
+.modrinth-date-picker :deep(.flatpickr-current-month .modrinth-hidden-cur-month) {
+	display: none;
+}
 .modrinth-date-picker :deep(.flatpickr-current-month .flatpickr-monthDropdown-months:disabled) {
 	@apply cursor-not-allowed opacity-40 hover:bg-surface-4;
 }
@@ -900,8 +1469,22 @@ defineExpose({
 	@apply border-transparent;
 }
 
-.modrinth-date-picker.show-today :deep(.flatpickr-day.today) {
-	@apply border-brand text-contrast;
+.modrinth-date-picker.show-today :deep(.flatpickr-day.today::after) {
+	content: '';
+	position: absolute;
+	bottom: 6px;
+	left: 50%;
+	width: 4px;
+	height: 4px;
+	border-radius: 9999px;
+	transform: translateX(-50%);
+	@apply bg-brand;
+}
+
+.modrinth-date-picker.show-today :deep(.flatpickr-day.today.selected::after),
+.modrinth-date-picker.show-today :deep(.flatpickr-day.today.startRange::after),
+.modrinth-date-picker.show-today :deep(.flatpickr-day.today.endRange::after) {
+	@apply bg-brand-inverted;
 }
 
 .modrinth-date-picker :deep(.flatpickr-day.selected),
@@ -911,7 +1494,7 @@ defineExpose({
 }
 
 .modrinth-date-picker :deep(.flatpickr-day.inRange) {
-	@apply rounded-none border-transparent bg-transparent text-contrast shadow-none hover:rounded-none hover:border-transparent hover:bg-transparent;
+	@apply rounded-none border-transparent bg-transparent text-brand shadow-none hover:rounded-none hover:border-transparent hover:bg-transparent;
 }
 
 .modrinth-date-picker :deep(.flatpickr-calendar.multiMonth .flatpickr-day.inRange) {
@@ -1001,6 +1584,15 @@ defineExpose({
 	right: 0;
 }
 
+.modrinth-date-picker.can-select-range :deep(.flatpickr-day:not(.flatpickr-disabled):not(.hidden)) {
+	cursor: pointer;
+}
+
+.modrinth-date-picker.is-selecting-range
+	:deep(.flatpickr-day:not(.flatpickr-disabled):not(.hidden)) {
+	cursor: grabbing;
+}
+
 .modrinth-date-picker.can-drag-range
 	:deep(.flatpickr-day.startRange:not(.endRange):not(.flatpickr-disabled)),
 .modrinth-date-picker.can-drag-range
@@ -1008,6 +1600,11 @@ defineExpose({
 	cursor: grab;
 }
 
+.modrinth-date-picker.is-moving-range-end
+	:deep(.flatpickr-day:not(.flatpickr-disabled):not(.hidden)) {
+	cursor: grabbing !important;
+}
+
 .modrinth-date-picker.is-dragging-range :deep(.flatpickr-day) {
 	cursor: grabbing !important;
 }
diff --git a/packages/ui/src/stories/base/DatePicker.stories.ts b/packages/ui/src/stories/base/DatePicker.stories.ts
index 27a492f8c..8a8838cb3 100644
--- a/packages/ui/src/stories/base/DatePicker.stories.ts
+++ b/packages/ui/src/stories/base/DatePicker.stories.ts
@@ -94,6 +94,28 @@ export const Range: Story = {
 	}),
 }
 
+export const SameDayRange: Story = {
+	render: () => ({
+		components: { DatePicker },
+		setup() {
+			const value = ref(['2026-04-27', '2026-04-27'])
+			return { value }
+		},
+		template: /* html */ `
+			<div class="flex max-w-sm flex-col gap-2">
+				<DatePicker
+					v-model="value"
+					wrapperClass="w-[350px]"
+					mode="range"
+					default-view-date="2026-04-01"
+					placeholder="Select a date range..."
+				/>
+				<p class="text-sm text-secondary">Selected value: {{ value?.join(' to ') || 'None' }}</p>
+			</div>
+		`,
+	}),
+}
+
 export const TwoMonthRange: Story = {
 	render: () => ({
 		components: { DatePicker },
@@ -125,7 +147,61 @@ export const TwoMonthRange: Story = {
 	}),
 }
 
-export const DraggableRange: Story = {
+export const TwoMonthRangeAlignedRight: Story = {
+	render: () => ({
+		components: { DatePicker },
+		setup() {
+			const value = ref(['2033-11-16', '2033-12-21'])
+			const datePicker = ref<InstanceType<typeof DatePicker> | null>(null)
+
+			onMounted(async () => {
+				await nextTick()
+				datePicker.value?.open()
+			})
+
+			return { datePicker, value }
+		},
+		template: /* html */ `
+			<div class="flex h-[460px] max-w-[700px] flex-col gap-2">
+				<DatePicker
+					ref="datePicker"
+					v-model="value"
+					wrapperClass="w-[350px]"
+					mode="range"
+					:show-months="2"
+					view-date-alignment="right"
+					placeholder="Select a date range..."
+				/>
+				<p class="text-sm text-secondary">Selected value: {{ value?.join(' to ') || 'None' }}</p>
+			</div>
+		`,
+	}),
+}
+
+export const TwoMonthCalendarOnlyRange: Story = {
+	render: () => ({
+		components: { DatePicker },
+		setup() {
+			const value = ref(['2033-11-16', '2033-12-21'])
+			return { value }
+		},
+		template: /* html */ `
+			<div class="flex max-w-[700px] flex-col gap-2">
+				<DatePicker
+					v-model="value"
+					wrapperClass="w-full"
+					mode="range"
+					:show-months="2"
+					calendar-only
+					default-view-date="2033-11-01"
+				/>
+				<p class="text-sm text-secondary">Selected value: {{ value?.join(' to ') || 'None' }}</p>
+			</div>
+		`,
+	}),
+}
+
+export const AdjustableRange: Story = {
 	render: () => ({
 		components: { DatePicker },
 		setup() {
@@ -150,6 +226,9 @@ export const DraggableRange: Story = {
 					placeholder="Select a date range..."
 				/>
 				<p class="text-sm text-secondary">Selected value: {{ value?.join(' to ') || 'None' }}</p>
+				<p class="text-xs text-secondary">
+					Drag either endpoint, or click an endpoint, hover to preview, and click another day to move it.
+				</p>
 			</div>
 		`,
 	}),
@@ -213,6 +292,35 @@ export const OpenCalendar: Story = {
 	}),
 }
 
+export const ForceAbove: Story = {
+	render: () => ({
+		components: { DatePicker },
+		setup() {
+			const value = ref('2026-06-15')
+			const datePicker = ref<InstanceType<typeof DatePicker> | null>(null)
+
+			onMounted(async () => {
+				await nextTick()
+				datePicker.value?.open()
+			})
+
+			return { datePicker, value }
+		},
+		template: /* html */ `
+			<div class="flex h-[420px] max-w-sm flex-col justify-end gap-2 pb-6">
+				<DatePicker
+					ref="datePicker"
+					v-model="value"
+					wrapperClass="w-[300px]"
+					default-view-date="2026-06-01"
+					position="above"
+				/>
+				<p class="text-sm text-secondary">Selected value: {{ value || 'None' }}</p>
+			</div>
+		`,
+	}),
+}
+
 export const PreserveDay: Story = {
 	render: () => ({
 		components: { DatePicker },
@@ -270,9 +378,67 @@ export const ShowToday: Story = {
 	}),
 }
 
+export const InsideClippedContainer: Story = {
+	render: () => ({
+		components: { DatePicker },
+		setup() {
+			const value = ref('2026-04-27')
+			const datePicker = ref<InstanceType<typeof DatePicker> | null>(null)
+
+			onMounted(async () => {
+				await nextTick()
+				datePicker.value?.open()
+			})
+
+			return { datePicker, value }
+		},
+		template: /* html */ `
+			<div class="h-[220px] w-[360px] overflow-hidden rounded-xl border border-solid border-surface-5 bg-surface-2 p-4">
+				<div class="flex flex-col gap-2">
+					<DatePicker
+						ref="datePicker"
+						v-model="value"
+						wrapperClass="w-[300px]"
+						placeholder="Select a date..."
+					/>
+					<p class="text-sm text-secondary">Selected value: {{ value || 'None' }}</p>
+				</div>
+			</div>
+		`,
+	}),
+}
+
 export const Disabled: Story = {
 	args: {
 		modelValue: '2026-04-27',
 		disabled: true,
 	},
 }
+
+export const CalendarClass: Story = {
+	render: () => ({
+		components: { DatePicker },
+		setup() {
+			const value = ref('2026-04-27')
+			const datePicker = ref<InstanceType<typeof DatePicker> | null>(null)
+
+			onMounted(async () => {
+				await nextTick()
+				datePicker.value?.open()
+			})
+
+			return { datePicker, value }
+		},
+		template: /* html */ `
+			<div class="flex h-[420px] max-w-sm flex-col gap-2">
+				<DatePicker
+					ref="datePicker"
+					v-model="value"
+					wrapperClass="w-[300px]"
+					calendar-class="ring-2 ring-brand"
+				/>
+				<p class="text-sm text-secondary">Calendar has a brand-colored ring applied via calendarClass.</p>
+			</div>
+		`,
+	}),
+}