A Date Is Not a Day

import { Temporal } from 'temporal-polyfill';
import type {
	Clock,
	EventTimeModel,
	EventTimeState,
	EventTimeViewModel,
	UserCalendarLabel,
} from './types';

/**
 * Maps a signed day distance in the user's calendar to the relative word the card shows.
 *
 * Falls back to `'date'` so anything beyond the near window renders as a formatted date rather than a misleading relative word.
 * The `'today'` case is exactly `daysUntil === 0`, which keeps the rendered word locked to the count it came from.
 *
 * @param daysUntil - The signed whole-day distance from the user's today to the event date.
 * @returns The relative word, or `'date'` when the event is outside the yesterday-to-tomorrow window.
 */
export function userCalendarLabel( daysUntil: number ): UserCalendarLabel {
	if ( daysUntil === -1 ) {
		return 'yesterday';
	}

	if ( daysUntil === 0 ) {
		return 'today';
	}

	if ( daysUntil === 1 ) {
		return 'tomorrow';
	}

	return 'date';
}

/**
 * Reads the user's calendar date "now" from an injected clock.
 *
 * Going through the clock rather than `Temporal.Now` directly is what lets a demo freeze "now".
 *
 * @param clock - The clock to read the current instant from.
 * @param timeZone - The IANA zone whose calendar date is wanted.
 * @returns The plain calendar date in that zone at the clock's instant.
 */
export function getTodayInZone( clock: Clock, timeZone: string ): Temporal.PlainDate {
	return clock.now.toZonedDateTimeISO( timeZone ).toPlainDate();
}

/**
 * Builds the product-facing cross-zone warning from the same-day boolean, or `null` when the dates match.
 *
 * The product's whole job is that nobody marks the wrong day, so the sentence names the real calendar date in each zone, not just the weekday.
 *
 * @param sameCalendarDay - Whether the event lands on one calendar date for both zones.
 * @param eventDate - The event's calendar date in the host's zone.
 * @param userDate - The event's calendar date in the user's zone.
 * @param locale - The BCP 47 locale the dates are formatted in.
 * @returns The warning sentence naming both dates, or `null` when both zones share the date.
 */
export function buildCrossZoneWarning(
	sameCalendarDay: boolean,
	eventDate: Temporal.PlainDate,
	userDate: Temporal.PlainDate,
	locale: string,
): string | null {
	if ( sameCalendarDay ) {
		return null;
	}

	const dateFields = { weekday: 'long', month: 'short', day: 'numeric' } as const;
	const hostDate = eventDate.toLocaleString( locale, dateFields );
	const yourDate = userDate.toLocaleString( locale, dateFields );

	return `Heads up: this session is listed as ${ hostDate } in the host's time zone, but it falls on ${ yourDate } for you.`;
}

/**
 * Derives everything the card renders from the parsed model and a clock.
 *
 * The instant is converted into both zones first, then the two plain dates are compared for the same-day question, and the calendar-day distance powers the today label.
 * No millisecond math touches the calendar-day count, so a DST day still counts as a single day.
 *
 * @param model - The parsed event inputs.
 * @param clock - The clock supplying "now" for the today label and countdown.
 * @param locale - The BCP 47 locale the cross-zone warning's dates are formatted in.
 * @returns The resolved view model the template reads from.
 */
export function deriveViewModel( model: EventTimeModel, clock: Clock, locale = 'en-US' ): EventTimeViewModel {
	const eventZonedDateTime = model.instant.toZonedDateTimeISO( model.eventZone );
	const userZonedDateTime = model.instant.toZonedDateTimeISO( model.userZone );
	const eventDateInEventZone = eventZonedDateTime.toPlainDate();
	const eventDateInUserZone = userZonedDateTime.toPlainDate();

	// The same-day question: one instant, two zones, compared as calendar dates.
	const sameCalendarDay = eventDateInEventZone.equals( eventDateInUserZone );

	// The today question runs off the same plain dates, against today in the user's zone.
	const todayInUserZone = getTodayInZone( clock, model.userZone );
	const daysUntilInUserCalendar = todayInUserZone.until(
		eventDateInUserZone,
		{ largestUnit: 'days' },
	).days;

	return {
		eventZonedDateTime,
		userZonedDateTime,
		eventDateInEventZone,
		eventDateInUserZone,
		sameCalendarDay,
		crossZoneWarning: buildCrossZoneWarning( sameCalendarDay, eventDateInEventZone, eventDateInUserZone, locale ),
		daysUntilInUserCalendar,
		userCalendarLabel: userCalendarLabel( daysUntilInUserCalendar ),
	};
}

/**
 * Parses the raw attributes into an `EventTimeModel`.
 *
 * This is the only place a string becomes a `Temporal.Instant`, so the parsing boundary stays in one spot.
 *
 * @param startsAt - The canonical start as an ISO 8601 instant string.
 * @param eventZone - The IANA zone that owns the event.
 * @param userZone - The IANA zone the user reads it in.
 * @returns The parsed model.
 */
export function parseEventTimeModel(
	startsAt: string,
	eventZone: string,
	userZone: string,
): EventTimeModel {
	return {
		instant: Temporal.Instant.from( startsAt ),
		eventZone,
		userZone,
	};
}

/**
 * Resolves the raw attributes into one of the three explicit states the card renders.
 *
 * A blank attribute is `missing-input`. A value that fails to parse, a malformed instant or an unknown IANA zone, is `invalid-input` carrying the real `RangeError` message, so a wrong assumption fails loudly instead of swallowing into the same blank as missing input.
 *
 * @param startsAt - The canonical start as an ISO 8601 instant string.
 * @param eventZone - The IANA zone that owns the event.
 * @param userZone - The IANA zone the user reads it in.
 * @param clock - The clock supplying "now" for the today label and countdown.
 * @param locale - The BCP 47 locale the warning and times are formatted in.
 * @returns The resolved state: missing input, invalid input with a message, or a ready view model.
 */
export function buildEventTimeState(
	startsAt: string,
	eventZone: string,
	userZone: string,
	clock: Clock,
	locale = 'en-US',
): EventTimeState {
	if ( ! startsAt || ! eventZone || ! userZone ) {
		return { status: 'missing-input' };
	}

	try {
		const model = parseEventTimeModel( startsAt, eventZone, userZone );
		return { status: 'ready', view: deriveViewModel( model, clock, locale ) };
	} catch ( error ) {
		const message = error instanceof Error ? error.message : 'The event time could not be parsed.';
		return { status: 'invalid-input', message };
	}
}

/**
 * Formats a zoned date-time for display, with explicit fields plus the zone name.
 *
 * The fields are listed one by one because the shorthand `dateStyle` and `timeStyle` together with `timeZoneName` throws a `TypeError: Invalid option`.
 *
 * @param value - The zoned date-time to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized string, including the short zone name.
 */
export function formatZonedDateTime( value: Temporal.ZonedDateTime, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
		hour: 'numeric',
		minute: '2-digit',
		timeZoneName: 'short',
	} );
}

/**
 * Formats a zoned date-time for display with the same fields as `formatZonedDateTime` but with no zone name.
 *
 * It deliberately omits the zone, so the wall-clock reading shows as if it were the viewer's own local time.
 * That's exactly the silent cross-zone bug the opener demo dramatizes, where a foreign zone's clock is presented with no qualifier and the reader blocks the wrong day.
 * Real product code should prefer `formatZonedDateTime` so the zone is never hidden; this exists only to stage that mistake on purpose.
 *
 * @param value - The zoned date-time to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized string, with no zone name.
 */
export function formatWallClockDateTime( value: Temporal.ZonedDateTime, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
		hour: 'numeric',
		minute: '2-digit',
	} );
}

/**
 * Formats a plain calendar date for display, with no time and no zone.
 *
 * Used for the `'date'` label, where a relative word would mislead, so the card shows the actual calendar date instead.
 *
 * @param value - The plain date to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized calendar date.
 */
export function formatPlainDate( value: Temporal.PlainDate, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
	} );
}

import { LitElement, html, css } from 'lit';
import { customElement, property, state } from 'lit/decorators.js';
import { Temporal } from 'temporal-polyfill';
import type { NaiveDayResult } from './types';

/**
 * The pre-Temporal baseline, laying three answers to the same-day question side by side.
 *
 * The first row is the bug the article opens on: the venue half is formatted in the event's zone on purpose, and the user half falls back to a simulated device zone instead of the selected user zone, so the two sides rest on different zone assumptions.
 * The second row passes the missing `timeZone` option and gets the right answer with plain Date and Intl.
 * The third row is the Temporal model, correct and reviewable.
 *
 * The device zone is a visible, pinned control, never a read of the reader's real host zone, so the broken row lies deterministically for every reader.
 *
 * @element event-day-naive
 */
@customElement( 'event-day-naive' )
export class EventDayNaive extends LitElement {

	/**
	 * The canonical event start as an ISO 8601 instant string.
	 */
	@property( { attribute: 'starts-at' } )
	startsAt = '2026-08-31T05:00:00Z';

	/**
	 * The IANA time zone that owns the event.
	 */
	@property( { attribute: 'event-time-zone' } )
	eventTimeZone = 'Europe/Berlin';

	/**
	 * The simulated device time zone the broken row reads instead of the selected user zone.
	 *
	 * Pinned to the host's `Europe/Berlin` so the broken user day matches the venue and the warning wrongly stays silent. It's a stand-in for `Intl.DateTimeFormat`'s default zone, never a read of where the reader runs it.
	 */
	@state()
	private deviceTimeZone = 'Europe/Berlin';

	/**
	 * The user zone the product actually selected, which the broken row ignores.
	 *
	 * Initialized to the neutral example `America/Los_Angeles`, a reader-controlled value, never a read of the host zone.
	 */
	@state()
	private userTimeZone = 'America/Los_Angeles';

	/**
	 * The zones offered in both selectors, a small set chosen so the divergence is easy to see.
	 */
	private readonly zones = [
		'Europe/Berlin',
		'America/Los_Angeles',
		'America/Argentina/Buenos_Aires',
		'Europe/London',
		'Asia/Tokyo',
	];

	/**
	 * Styles for the harness, scoped to its shadow root.
	 */
	static styles = css`
		:host {
			display: block;
			height: 100%;
			font-family: var( --font-sans, system-ui, sans-serif );
			color: var( --ink, #17171a );
		}

		.wrap {
			display: grid;
			gap: 18px;
			padding: 22px;
		}

		.controls {
			display: flex;
			flex-wrap: wrap;
			gap: 16px;
		}

		label {
			display: flex;
			flex-direction: column;
			gap: 6px;
		}

		.lbl {
			font-family: var( --font-mono, monospace );
			font-size: 10px;
			letter-spacing: 0.08em;
			text-transform: uppercase;
			color: var( --ink-faint, #71717b );
		}

		select {
			font-family: var( --font-sans, sans-serif );
			font-size: 14px;
			color: var( --ink, #17171a );
			background: var( --bg, #fcfcfb );
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: 7px;
			padding: 8px 10px;
		}

		table {
			width: 100%;
			border-collapse: collapse;
			font-size: 13.5px;
		}

		th,
		td {
			text-align: left;
			padding: 9px 10px;
			border-bottom: 1px solid var( --line, #e7e6e2 );
		}

		th {
			font-family: var( --font-mono, monospace );
			font-size: 10px;
			letter-spacing: 0.06em;
			text-transform: uppercase;
			color: var( --ink-faint, #71717b );
			font-weight: 600;
		}

		.same.yes {
			color: color-mix( in srgb, #1f9d5b 65%, var( --ink, #17171a ) );
			font-weight: 600;
		}

		.same.no {
			color: color-mix( in srgb, #cc3b41 65%, var( --ink, #17171a ) );
			font-weight: 600;
		}

		.tag {
			display: inline-block;
			border-radius: 999px;
			padding: 2px 9px;
			font-family: var( --font-mono, monospace );
			font-size: 10.5px;
		}

		.tag.wrong {
			background: rgb( 204 59 65 / 0.12 );
			color: color-mix( in srgb, #cc3b41 65%, var( --ink, #17171a ) );
		}

		.tag.right {
			background: rgb( 31 157 91 / 0.12 );
			color: color-mix( in srgb, #1f9d5b 65%, var( --ink, #17171a ) );
		}

		.hint {
			margin: 0;
			font-family: var( --font-mono, monospace );
			font-size: 10.5px;
			line-height: 1.6;
			color: var( --ink-soft, #56565c );
		}
	`;

	/**
	 * Formats one instant as a same-locale day string in a given zone, the Date-and-Intl way the baseline uses.
	 *
	 * The comparison downstream only holds because both sides use this same locale and options. `Intl` output is locale-formatted text, not a guaranteed ISO string, so it must never be compared to a hardcoded constant.
	 *
	 * @param instant - The moment to format.
	 * @param timeZone - The zone to format it in.
	 * @returns The day string in that zone, in the `en-CA` format.
	 */
	private calendarDayTextInZone( instant: Date, timeZone: string ): string {
		return new Intl.DateTimeFormat( 'en-CA', {
			timeZone,
			year: 'numeric',
			month: '2-digit',
			day: '2-digit',
		} ).format( instant );
	}

	/**
	 * Computes the three approaches against the current zones.
	 *
	 * The broken row reads `deviceTimeZone` for the user side, the minimum-fix row reads `userTimeZone`, and the Temporal row compares plain dates after converting the instant into each zone.
	 *
	 * @returns The three labeled result rows, in display order.
	 */
	private get results(): NaiveDayResult[] {
		const date = new Date( this.startsAt );
		const hostDay = this.calendarDayTextInZone( date, this.eventTimeZone );

		// Broken: the user side falls back to the simulated device zone, not the selected user zone.
		const brokenUserDay = this.calendarDayTextInZone( date, this.deviceTimeZone );

		// Minimum fix: pass the selected user zone to the user side.
		const fixedUserDay = this.calendarDayTextInZone( date, this.userTimeZone );

		// Temporal model: convert the instant into each zone, then compare calendar dates.
		const instant = Temporal.Instant.from( this.startsAt );
		const eventDate = instant.toZonedDateTimeISO( this.eventTimeZone ).toPlainDate();
		const userDate = instant.toZonedDateTimeISO( this.userTimeZone ).toPlainDate();
		const temporalSameDay = eventDate.equals( userDate );

		const correctSameDay = hostDay === fixedUserDay;

		return [
			{
				approach: 'Broken Date + Intl',
				userDay: brokenUserDay,
				sameCalendarDay: hostDay === brokenUserDay,
				// Truthful even in the device-equals-user edge case: the broken row is only
				// "correct" when its same-day answer happens to match the right one, which it
				// does when the device zone and the selected user zone are the same.
				correct: ( hostDay === brokenUserDay ) === correctSameDay,
			},
			{
				approach: 'Minimum Date + Intl fix',
				userDay: fixedUserDay,
				sameCalendarDay: correctSameDay,
				correct: true,
			},
			{
				approach: 'Temporal model',
				userDay: userDate.toString(),
				sameCalendarDay: temporalSameDay,
				correct: true,
			},
		];
	}

	/**
	 * Updates the simulated device zone from its selector.
	 *
	 * @param event - The change event from the device-zone select.
	 */
	private onDeviceChange = ( event: Event ): void => {
		if ( event.target instanceof HTMLSelectElement ) {
			this.deviceTimeZone = event.target.value;
		}
	};

	/**
	 * Updates the selected user zone from its selector.
	 *
	 * @param event - The change event from the user-zone select.
	 */
	private onUserChange = ( event: Event ): void => {
		if ( event.target instanceof HTMLSelectElement ) {
			this.userTimeZone = event.target.value;
		}
	};

	/**
	 * Renders the two zone selectors and the three-row comparison table.
	 */
	render() {
		const results = this.results;
		const [ broken ] = results;
		// The broken row's verdict depends on both selectors, so the hint tracks the current controls rather than assuming the Berlin default.
		const brokenState = broken.correct
			? 'Right now it happens to match the correct answer, but only because the simulated device zone produces the same calendar-day answer as the selected user zone.'
			: 'Right now it\'s wrong, because the simulated device zone produces a different calendar-day answer than the selected user zone.';

		return html`
			<div class="wrap">
				<div class="controls">
					<label>
						<span class="lbl">Simulated device zone</span>
						<select @change=${ this.onDeviceChange }>
							${ this.zones.map(
								( zone ) => html`<option value=${ zone } ?selected=${ zone === this.deviceTimeZone }>${ zone }</option>`,
							) }
						</select>
					</label>
					<label>
						<span class="lbl">Selected user zone</span>
						<select @change=${ this.onUserChange }>
							${ this.zones.map(
								( zone ) => html`<option value=${ zone } ?selected=${ zone === this.userTimeZone }>${ zone }</option>`,
							) }
						</select>
					</label>
				</div>
				<table>
					<thead>
						<tr>
							<th>Approach</th>
							<th>User day</th>
							<th>Same day?</th>
							<th>Verdict</th>
						</tr>
					</thead>
					<tbody>
						${ results.map(
							( result ) => html`
								<tr>
									<td>${ result.approach }</td>
									<td>${ result.userDay }</td>
									<td class=${ result.sameCalendarDay ? 'same yes' : 'same no' }>
										${ result.sameCalendarDay ? 'yes' : 'no' }
									</td>
									<td>
										<span class=${ result.correct ? 'tag right' : 'tag wrong' }>
											${ result.correct ? 'correct' : 'wrong' }
										</span>
									</td>
								</tr>
							`,
						) }
					</tbody>
				</table>
				<p class="hint">
					The broken row formats the user side in the simulated device zone, not the selected user zone. ${ brokenState }
				</p>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'event-day-naive': EventDayNaive;
	}
}

import { Temporal } from 'temporal-polyfill';
import type {
	Clock,
	EventTimeModel,
	EventTimeState,
	EventTimeViewModel,
	UserCalendarLabel,
} from './types';

/**
 * Maps a signed day distance in the user's calendar to the relative word the card shows.
 *
 * Falls back to `'date'` so anything beyond the near window renders as a formatted date rather than a misleading relative word.
 * The `'today'` case is exactly `daysUntil === 0`, which keeps the rendered word locked to the count it came from.
 *
 * @param daysUntil - The signed whole-day distance from the user's today to the event date.
 * @returns The relative word, or `'date'` when the event is outside the yesterday-to-tomorrow window.
 */
export function userCalendarLabel( daysUntil: number ): UserCalendarLabel {
	if ( daysUntil === -1 ) {
		return 'yesterday';
	}

	if ( daysUntil === 0 ) {
		return 'today';
	}

	if ( daysUntil === 1 ) {
		return 'tomorrow';
	}

	return 'date';
}

/**
 * Reads the user's calendar date "now" from an injected clock.
 *
 * Going through the clock rather than `Temporal.Now` directly is what lets a demo freeze "now".
 *
 * @param clock - The clock to read the current instant from.
 * @param timeZone - The IANA zone whose calendar date is wanted.
 * @returns The plain calendar date in that zone at the clock's instant.
 */
export function getTodayInZone( clock: Clock, timeZone: string ): Temporal.PlainDate {
	return clock.now.toZonedDateTimeISO( timeZone ).toPlainDate();
}

/**
 * Builds the product-facing cross-zone warning from the same-day boolean, or `null` when the dates match.
 *
 * The product's whole job is that nobody marks the wrong day, so the sentence names the real calendar date in each zone, not just the weekday.
 *
 * @param sameCalendarDay - Whether the event lands on one calendar date for both zones.
 * @param eventDate - The event's calendar date in the host's zone.
 * @param userDate - The event's calendar date in the user's zone.
 * @param locale - The BCP 47 locale the dates are formatted in.
 * @returns The warning sentence naming both dates, or `null` when both zones share the date.
 */
export function buildCrossZoneWarning(
	sameCalendarDay: boolean,
	eventDate: Temporal.PlainDate,
	userDate: Temporal.PlainDate,
	locale: string,
): string | null {
	if ( sameCalendarDay ) {
		return null;
	}

	const dateFields = { weekday: 'long', month: 'short', day: 'numeric' } as const;
	const hostDate = eventDate.toLocaleString( locale, dateFields );
	const yourDate = userDate.toLocaleString( locale, dateFields );

	return `Heads up: this session is listed as ${ hostDate } in the host's time zone, but it falls on ${ yourDate } for you.`;
}

/**
 * Derives everything the card renders from the parsed model and a clock.
 *
 * The instant is converted into both zones first, then the two plain dates are compared for the same-day question, and the calendar-day distance powers the today label.
 * No millisecond math touches the calendar-day count, so a DST day still counts as a single day.
 *
 * @param model - The parsed event inputs.
 * @param clock - The clock supplying "now" for the today label and countdown.
 * @param locale - The BCP 47 locale the cross-zone warning's dates are formatted in.
 * @returns The resolved view model the template reads from.
 */
export function deriveViewModel( model: EventTimeModel, clock: Clock, locale = 'en-US' ): EventTimeViewModel {
	const eventZonedDateTime = model.instant.toZonedDateTimeISO( model.eventZone );
	const userZonedDateTime = model.instant.toZonedDateTimeISO( model.userZone );
	const eventDateInEventZone = eventZonedDateTime.toPlainDate();
	const eventDateInUserZone = userZonedDateTime.toPlainDate();

	// The same-day question: one instant, two zones, compared as calendar dates.
	const sameCalendarDay = eventDateInEventZone.equals( eventDateInUserZone );

	// The today question runs off the same plain dates, against today in the user's zone.
	const todayInUserZone = getTodayInZone( clock, model.userZone );
	const daysUntilInUserCalendar = todayInUserZone.until(
		eventDateInUserZone,
		{ largestUnit: 'days' },
	).days;

	return {
		eventZonedDateTime,
		userZonedDateTime,
		eventDateInEventZone,
		eventDateInUserZone,
		sameCalendarDay,
		crossZoneWarning: buildCrossZoneWarning( sameCalendarDay, eventDateInEventZone, eventDateInUserZone, locale ),
		daysUntilInUserCalendar,
		userCalendarLabel: userCalendarLabel( daysUntilInUserCalendar ),
	};
}

/**
 * Parses the raw attributes into an `EventTimeModel`.
 *
 * This is the only place a string becomes a `Temporal.Instant`, so the parsing boundary stays in one spot.
 *
 * @param startsAt - The canonical start as an ISO 8601 instant string.
 * @param eventZone - The IANA zone that owns the event.
 * @param userZone - The IANA zone the user reads it in.
 * @returns The parsed model.
 */
export function parseEventTimeModel(
	startsAt: string,
	eventZone: string,
	userZone: string,
): EventTimeModel {
	return {
		instant: Temporal.Instant.from( startsAt ),
		eventZone,
		userZone,
	};
}

/**
 * Resolves the raw attributes into one of the three explicit states the card renders.
 *
 * A blank attribute is `missing-input`. A value that fails to parse, a malformed instant or an unknown IANA zone, is `invalid-input` carrying the real `RangeError` message, so a wrong assumption fails loudly instead of swallowing into the same blank as missing input.
 *
 * @param startsAt - The canonical start as an ISO 8601 instant string.
 * @param eventZone - The IANA zone that owns the event.
 * @param userZone - The IANA zone the user reads it in.
 * @param clock - The clock supplying "now" for the today label and countdown.
 * @param locale - The BCP 47 locale the warning and times are formatted in.
 * @returns The resolved state: missing input, invalid input with a message, or a ready view model.
 */
export function buildEventTimeState(
	startsAt: string,
	eventZone: string,
	userZone: string,
	clock: Clock,
	locale = 'en-US',
): EventTimeState {
	if ( ! startsAt || ! eventZone || ! userZone ) {
		return { status: 'missing-input' };
	}

	try {
		const model = parseEventTimeModel( startsAt, eventZone, userZone );
		return { status: 'ready', view: deriveViewModel( model, clock, locale ) };
	} catch ( error ) {
		const message = error instanceof Error ? error.message : 'The event time could not be parsed.';
		return { status: 'invalid-input', message };
	}
}

/**
 * Formats a zoned date-time for display, with explicit fields plus the zone name.
 *
 * The fields are listed one by one because the shorthand `dateStyle` and `timeStyle` together with `timeZoneName` throws a `TypeError: Invalid option`.
 *
 * @param value - The zoned date-time to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized string, including the short zone name.
 */
export function formatZonedDateTime( value: Temporal.ZonedDateTime, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
		hour: 'numeric',
		minute: '2-digit',
		timeZoneName: 'short',
	} );
}

/**
 * Formats a zoned date-time for display with the same fields as `formatZonedDateTime` but with no zone name.
 *
 * It deliberately omits the zone, so the wall-clock reading shows as if it were the viewer's own local time.
 * That's exactly the silent cross-zone bug the opener demo dramatizes, where a foreign zone's clock is presented with no qualifier and the reader blocks the wrong day.
 * Real product code should prefer `formatZonedDateTime` so the zone is never hidden; this exists only to stage that mistake on purpose.
 *
 * @param value - The zoned date-time to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized string, with no zone name.
 */
export function formatWallClockDateTime( value: Temporal.ZonedDateTime, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
		hour: 'numeric',
		minute: '2-digit',
	} );
}

/**
 * Formats a plain calendar date for display, with no time and no zone.
 *
 * Used for the `'date'` label, where a relative word would mislead, so the card shows the actual calendar date instead.
 *
 * @param value - The plain date to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized calendar date.
 */
export function formatPlainDate( value: Temporal.PlainDate, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
	} );
}

import { Temporal } from 'temporal-polyfill';
import type {
	Clock,
	EventTimeModel,
	EventTimeState,
	EventTimeViewModel,
	UserCalendarLabel,
} from './types';

/**
 * Maps a signed day distance in the user's calendar to the relative word the card shows.
 *
 * Falls back to `'date'` so anything beyond the near window renders as a formatted date rather than a misleading relative word.
 * The `'today'` case is exactly `daysUntil === 0`, which keeps the rendered word locked to the count it came from.
 *
 * @param daysUntil - The signed whole-day distance from the user's today to the event date.
 * @returns The relative word, or `'date'` when the event is outside the yesterday-to-tomorrow window.
 */
export function userCalendarLabel( daysUntil: number ): UserCalendarLabel {
	if ( daysUntil === -1 ) {
		return 'yesterday';
	}

	if ( daysUntil === 0 ) {
		return 'today';
	}

	if ( daysUntil === 1 ) {
		return 'tomorrow';
	}

	return 'date';
}

/**
 * Reads the user's calendar date "now" from an injected clock.
 *
 * Going through the clock rather than `Temporal.Now` directly is what lets a demo freeze "now".
 *
 * @param clock - The clock to read the current instant from.
 * @param timeZone - The IANA zone whose calendar date is wanted.
 * @returns The plain calendar date in that zone at the clock's instant.
 */
export function getTodayInZone( clock: Clock, timeZone: string ): Temporal.PlainDate {
	return clock.now.toZonedDateTimeISO( timeZone ).toPlainDate();
}

/**
 * Builds the product-facing cross-zone warning from the same-day boolean, or `null` when the dates match.
 *
 * The product's whole job is that nobody marks the wrong day, so the sentence names the real calendar date in each zone, not just the weekday.
 *
 * @param sameCalendarDay - Whether the event lands on one calendar date for both zones.
 * @param eventDate - The event's calendar date in the host's zone.
 * @param userDate - The event's calendar date in the user's zone.
 * @param locale - The BCP 47 locale the dates are formatted in.
 * @returns The warning sentence naming both dates, or `null` when both zones share the date.
 */
export function buildCrossZoneWarning(
	sameCalendarDay: boolean,
	eventDate: Temporal.PlainDate,
	userDate: Temporal.PlainDate,
	locale: string,
): string | null {
	if ( sameCalendarDay ) {
		return null;
	}

	const dateFields = { weekday: 'long', month: 'short', day: 'numeric' } as const;
	const hostDate = eventDate.toLocaleString( locale, dateFields );
	const yourDate = userDate.toLocaleString( locale, dateFields );

	return `Heads up: this session is listed as ${ hostDate } in the host's time zone, but it falls on ${ yourDate } for you.`;
}

/**
 * Derives everything the card renders from the parsed model and a clock.
 *
 * The instant is converted into both zones first, then the two plain dates are compared for the same-day question, and the calendar-day distance powers the today label.
 * No millisecond math touches the calendar-day count, so a DST day still counts as a single day.
 *
 * @param model - The parsed event inputs.
 * @param clock - The clock supplying "now" for the today label and countdown.
 * @param locale - The BCP 47 locale the cross-zone warning's dates are formatted in.
 * @returns The resolved view model the template reads from.
 */
export function deriveViewModel( model: EventTimeModel, clock: Clock, locale = 'en-US' ): EventTimeViewModel {
	const eventZonedDateTime = model.instant.toZonedDateTimeISO( model.eventZone );
	const userZonedDateTime = model.instant.toZonedDateTimeISO( model.userZone );
	const eventDateInEventZone = eventZonedDateTime.toPlainDate();
	const eventDateInUserZone = userZonedDateTime.toPlainDate();

	// The same-day question: one instant, two zones, compared as calendar dates.
	const sameCalendarDay = eventDateInEventZone.equals( eventDateInUserZone );

	// The today question runs off the same plain dates, against today in the user's zone.
	const todayInUserZone = getTodayInZone( clock, model.userZone );
	const daysUntilInUserCalendar = todayInUserZone.until(
		eventDateInUserZone,
		{ largestUnit: 'days' },
	).days;

	return {
		eventZonedDateTime,
		userZonedDateTime,
		eventDateInEventZone,
		eventDateInUserZone,
		sameCalendarDay,
		crossZoneWarning: buildCrossZoneWarning( sameCalendarDay, eventDateInEventZone, eventDateInUserZone, locale ),
		daysUntilInUserCalendar,
		userCalendarLabel: userCalendarLabel( daysUntilInUserCalendar ),
	};
}

/**
 * Parses the raw attributes into an `EventTimeModel`.
 *
 * This is the only place a string becomes a `Temporal.Instant`, so the parsing boundary stays in one spot.
 *
 * @param startsAt - The canonical start as an ISO 8601 instant string.
 * @param eventZone - The IANA zone that owns the event.
 * @param userZone - The IANA zone the user reads it in.
 * @returns The parsed model.
 */
export function parseEventTimeModel(
	startsAt: string,
	eventZone: string,
	userZone: string,
): EventTimeModel {
	return {
		instant: Temporal.Instant.from( startsAt ),
		eventZone,
		userZone,
	};
}

/**
 * Resolves the raw attributes into one of the three explicit states the card renders.
 *
 * A blank attribute is `missing-input`. A value that fails to parse, a malformed instant or an unknown IANA zone, is `invalid-input` carrying the real `RangeError` message, so a wrong assumption fails loudly instead of swallowing into the same blank as missing input.
 *
 * @param startsAt - The canonical start as an ISO 8601 instant string.
 * @param eventZone - The IANA zone that owns the event.
 * @param userZone - The IANA zone the user reads it in.
 * @param clock - The clock supplying "now" for the today label and countdown.
 * @param locale - The BCP 47 locale the warning and times are formatted in.
 * @returns The resolved state: missing input, invalid input with a message, or a ready view model.
 */
export function buildEventTimeState(
	startsAt: string,
	eventZone: string,
	userZone: string,
	clock: Clock,
	locale = 'en-US',
): EventTimeState {
	if ( ! startsAt || ! eventZone || ! userZone ) {
		return { status: 'missing-input' };
	}

	try {
		const model = parseEventTimeModel( startsAt, eventZone, userZone );
		return { status: 'ready', view: deriveViewModel( model, clock, locale ) };
	} catch ( error ) {
		const message = error instanceof Error ? error.message : 'The event time could not be parsed.';
		return { status: 'invalid-input', message };
	}
}

/**
 * Formats a zoned date-time for display, with explicit fields plus the zone name.
 *
 * The fields are listed one by one because the shorthand `dateStyle` and `timeStyle` together with `timeZoneName` throws a `TypeError: Invalid option`.
 *
 * @param value - The zoned date-time to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized string, including the short zone name.
 */
export function formatZonedDateTime( value: Temporal.ZonedDateTime, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
		hour: 'numeric',
		minute: '2-digit',
		timeZoneName: 'short',
	} );
}

/**
 * Formats a zoned date-time for display with the same fields as `formatZonedDateTime` but with no zone name.
 *
 * It deliberately omits the zone, so the wall-clock reading shows as if it were the viewer's own local time.
 * That's exactly the silent cross-zone bug the opener demo dramatizes, where a foreign zone's clock is presented with no qualifier and the reader blocks the wrong day.
 * Real product code should prefer `formatZonedDateTime` so the zone is never hidden; this exists only to stage that mistake on purpose.
 *
 * @param value - The zoned date-time to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized string, with no zone name.
 */
export function formatWallClockDateTime( value: Temporal.ZonedDateTime, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
		hour: 'numeric',
		minute: '2-digit',
	} );
}

/**
 * Formats a plain calendar date for display, with no time and no zone.
 *
 * Used for the `'date'` label, where a relative word would mislead, so the card shows the actual calendar date instead.
 *
 * @param value - The plain date to format.
 * @param locale - The BCP 47 locale tag to format in.
 * @returns The localized calendar date.
 */
export function formatPlainDate( value: Temporal.PlainDate, locale: string ): string {
	return value.toLocaleString( locale, {
		year: 'numeric',
		month: 'short',
		day: 'numeric',
	} );
}

import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { Temporal } from 'temporal-polyfill';
import {
	buildEventTimeState,
	formatPlainDate,
	formatZonedDateTime,
} from './event-time-model';
import type {
	Clock,
	EventTimeChangeDetail,
	EventTimeEventMap,
	EventTimeState,
	EventTimeViewModel,
} from './types';

/**
 * An event card that answers two questions about one instant across two time zones.
 *
 * It parses `starts-at` as an instant, converts it into the event zone and the user zone, and reports whether the event is the same calendar day for both, plus whether it reads as today, tomorrow, or yesterday on the user's calendar.
 * The user time zone is a required product input, not a machine read, and "now" comes from an injectable clock so a demo can freeze it.
 *
 * @element event-time
 * @fires event-time-change - Fired after each render with the two resolved answers, carrying an `EventTimeChangeDetail`.
 * @cssprop [--event-time-radius=12px] - The card's corner radius.
 */
@customElement( 'event-time' )
export class EventTime extends LitElement {

	/**
	 * The canonical start of the event as an ISO 8601 instant string.
	 * It's an instant on purpose, the one moment the event happens, not a calendar date, so every zone reads it consistently.
	 * It's a required input with no default; until a consumer sets it the card renders the neutral missing-input state.
	 */
	@property( { attribute: 'starts-at' } )
	startsAt!: string;

	/**
	 * The IANA time zone that owns the event, a product rule for the venue.
	 * It's a required input with no default, the same as the other two, so the venue zone is always a product decision.
	 */
	@property( { attribute: 'event-time-zone' } )
	eventTimeZone!: string;

	/**
	 * The IANA time zone the user reads the event in.
	 * This is a required input with no default, never the host zone, because letting the user's machine silently decide product behavior is the bug this component exists to avoid.
	 * A consumer that hasn't set it yet renders the neutral missing-input placeholder rather than leaking the rendering machine's zone.
	 */
	@property( { attribute: 'user-time-zone' } )
	userTimeZone!: string;

	/**
	 * The BCP 47 locale the times are formatted in.
	 */
	@property( { attribute: 'locale' } )
	locale = 'en-US';

	/**
	 * The clock the today label and the countdown read "now" from.
	 *
	 * Defaults to a clock backed by `Temporal.Now.instant()`, read once per component update. A fresh-reading getter doesn't re-render Lit on its own, so the label only recomputes when the component updates; if it must change while the card is open, schedule an update at the next local midnight or pass a clock driven from app state.
	 * A demo replaces it with a frozen instant so the rendered label and countdown are deterministic. It's a property, not an attribute, because a `Temporal.Instant` isn't a string.
	 */
	@property( { attribute: false } )
	clock: Clock = {
		get now(): Temporal.Instant {
			return Temporal.Now.instant();
		},
	};

	/**
	 * Styles for the component, scoped to its shadow root.
	 */
	static styles = css`
		:host {
			display: block;
			font-family: var( --font-sans, system-ui, sans-serif );
			color: var( --ink, #17171a );
		}

		.card {
			border: 1px solid var( --line, #e7e6e2 );
			border-radius: var( --event-time-radius, 12px );
			background: var( --surface, #fff );
			padding: 1.25rem 1.4rem;
			max-width: 30rem;
		}

		.title {
			margin: 0 0 0.9rem;
			font-size: 1.05rem;
			font-weight: 600;
			letter-spacing: -0.01em;
		}

		.rows {
			display: grid;
			gap: 0.55rem;
			margin: 0;
		}

		.row {
			display: grid;
			grid-template-columns: 7.5rem 1fr;
			gap: 0.5rem;
			align-items: baseline;
		}

		.row dt {
			font-family: var( --font-mono, monospace );
			font-size: 0.72rem;
			letter-spacing: 0.04em;
			text-transform: uppercase;
			color: var( --ink-faint, #71717b );
		}

		.row dd {
			margin: 0;
			font-size: 0.95rem;
		}

		.warning {
			margin: 1.1rem 0 0;
			border-radius: 10px;
			border: 1px solid color-mix( in srgb, #c8860a 38%, var( --surface, #fff ) );
			background: color-mix( in srgb, #c8860a 13%, var( --surface, #fff ) );
			padding: 0.6rem 0.8rem;
			font-size: 0.9rem;
			line-height: 1.5;
			color: color-mix( in srgb, #c8860a 60%, var( --ink, #17171a ) );
		}

		.label {
			margin: 1.1rem 0 0;
			font-size: 0.95rem;
		}

		.label .word {
			font-weight: 600;
		}

		.error {
			margin: 0;
			font-size: 0.9rem;
			color: color-mix( in srgb, #cc3b41 65%, var( --ink, #17171a ) );
		}

		.error code {
			font-family: var( --font-mono, monospace );
			font-size: 0.82rem;
		}
	`;

	/**
	 * Types `addEventListener( 'event-time-change', ... )` so the listener receives a `CustomEvent<EventTimeChangeDetail>` with no cast.
	 * Falls through to the standard signature for every other event.
	 */
	addEventListener<K extends keyof EventTimeEventMap>(
		type: K,
		listener: ( this: EventTime, ev: EventTimeEventMap[ K ] ) => void,
		options?: boolean | AddEventListenerOptions,
	): void;
	addEventListener(
		type: string,
		listener: EventListenerOrEventListenerObject,
		options?: boolean | AddEventListenerOptions,
	): void {
		super.addEventListener( type, listener, options );
	}

	/**
	 * The resolved state derived once per update in `willUpdate`: missing input, invalid input, or a ready view model.
	 *
	 * Both `render` and `updated` read this single value rather than re-deriving, so the "derive once" rule the card teaches also holds inside the card.
	 * Modeling the three states explicitly, rather than collapsing them to a nullable view, is the same discipline the model applies to time: a missing input and a bad input are different answers and the card shows different things for each.
	 */
	private state: EventTimeState = { status: 'missing-input' };

	/**
	 * Derives the state once before each render, reading the injected clock a single time.
	 *
	 * Doing the derivation here rather than in a getter means `render` and `updated` share one computed value, so the clock is read once per update and the today label can never disagree with the count the event reports.
	 *
	 */
	protected willUpdate(): void {
		this.state = buildEventTimeState( this.startsAt, this.eventTimeZone, this.userTimeZone, this.clock, this.locale );
	}

	/**
	 * Dispatches the typed `event-time-change` event after each successful render.
	 *
	 * It's `composed` so it crosses the shadow boundary and `bubbles` so a listener on the host receives it.
	 *
	 * @param view - The view model that was just rendered.
	 */
	private emitChange( view: EventTimeViewModel ): void {
		this.dispatchEvent(
			new CustomEvent<EventTimeChangeDetail>( 'event-time-change', {
				detail: {
					sameCalendarDay: view.sameCalendarDay,
					userCalendarLabel: view.userCalendarLabel,
					daysUntilInUserCalendar: view.daysUntilInUserCalendar,
				},
				bubbles: true,
				composed: true,
			} ),
		);
	}

	/**
	 * Lifecycle hook that emits the change event once the resolved render is in the DOM.
	 *
	 */
	protected updated(): void {
		if ( this.state.status === 'ready' ) {
			this.emitChange( this.state.view );
		}
	}

	/**
	 * Renders the card for whichever state the inputs resolved to.
	 *
	 * Missing input shows a neutral prompt, invalid input shows the real parse error, and a ready model shows the two times, the cross-zone warning when the dates differ, and the user-calendar label.
	 */
	render() {
		if ( this.state.status === 'missing-input' ) {
			return html`
				<div class="card">
					<p class="error">
						Set <code>starts-at</code>, <code>event-time-zone</code>, and <code>user-time-zone</code> to render the card.
					</p>
				</div>
			`;
		}

		if ( this.state.status === 'invalid-input' ) {
			return html`
				<div class="card">
					<p class="error">
						That event time could not be read: <code>${ this.state.message }</code>
					</p>
				</div>
			`;
		}

		const view = this.state.view;
		const userDay = view.userCalendarLabel === 'date'
			? formatPlainDate( view.eventDateInUserZone, this.locale )
			: view.userCalendarLabel;

		return html`
			<div class="card">
				<h2 class="title">Online workshop</h2>
				<dl class="rows">
					<div class="row">
						<dt>Venue time</dt>
						<dd>${ formatZonedDateTime( view.eventZonedDateTime, this.locale ) }</dd>
					</div>
					<div class="row">
						<dt>Your time</dt>
						<dd>${ formatZonedDateTime( view.userZonedDateTime, this.locale ) }</dd>
					</div>
				</dl>
				${ view.crossZoneWarning
					? html`<p class="warning">${ view.crossZoneWarning }</p>`
					: null }
				<p class="label">
					On your calendar this is <span class="word">${ userDay }</span>.
				</p>
			</div>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'event-time': EventTime;
	}
}