@optique/temporal 1.0.0-dev.921 → 1.0.0

package/dist/index.cjs

@@ -46,8 +46,15 @@ function instant(options = {}) {
 	const metavar = options.metavar ?? "TIMESTAMP";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.Instant.from("1970-01-01T00:00:00Z");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -86,8 +93,15 @@ function duration(options = {}) {
 	const metavar = options.metavar ?? "DURATION";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.Duration.from("PT0S");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -125,8 +139,15 @@ function zonedDateTime(options = {}) {
 	const metavar = options.metavar ?? "ZONED_DATETIME";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.ZonedDateTime.from("1970-01-01T00:00:00+00:00[UTC]");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -148,6 +169,64 @@ function zonedDateTime(options = {}) {
 	};
 }
 /**
+* Optional RFC 9557 calendar annotation suffix, e.g. `[u-ca=gregory]`.
+* Accepts case-insensitive values and the optional critical flag (`!`).
+* Used by all plain Temporal regexes to accept `toString()` output for
+* non-ISO calendars.
+*/
+const CALENDAR_ANNOTATION = String.raw`(\[!?u-ca=[a-zA-Z0-9\-]+\])?`;
+/**
+* Required RFC 9557 calendar annotation (non-optional variant used when the
+* annotation must be present, e.g. for reference-day/year forms).
+*/
+const CALENDAR_ANNOTATION_REQUIRED = String.raw`\[!?u-ca=[a-zA-Z0-9\-]+\]`;
+/**
+* Year portion: either 4 digits (`YYYY`) or a sign-prefixed 6-digit expanded
+* year (`+YYYYYY` / `-YYYYYY`).
+*/
+const YEAR = String.raw`([+-]\d{6}|\d{4})`;
+/** ISO 8601 fractional seconds with `.` or `,` separator. */
+const FRACTIONAL = String.raw`[.,]\d+`;
+/** Extended date: `YYYY-MM-DD` or `±YYYYYY-MM-DD`. */
+const DATE_EXTENDED = `${YEAR}-\\d{2}-\\d{2}`;
+/** Basic date: `YYYYMMDD` or `±YYYYYYMMDD`. */
+const DATE_BASIC = `${YEAR}\\d{4}`;
+/** Extended time: `HH:MM[:SS[.frac]]`. */
+const TIME_EXTENDED = `\\d{2}:\\d{2}(:\\d{2}(${FRACTIONAL})?)?`;
+/** Basic time: `HH`, `HHMM`, or `HHMMSS[.frac]`. */
+const TIME_BASIC = `\\d{2}(\\d{2}(\\d{2}(${FRACTIONAL})?)?)?`;
+/**
+* Matches YYYY-MM-DD (extended) or YYYYMMDD (basic) date forms only (no time
+* component).  Both forms accept expanded years and calendar annotations.
+*/
+const PLAIN_DATE_RE = /* @__PURE__ */ new RegExp(`^(${DATE_EXTENDED}|${DATE_BASIC})${CALENDAR_ANNOTATION}$`);
+/**
+* Matches time forms only (no date prefix).  Accepts extended
+* (`HH:MM[:SS[.frac]]`), basic (`HH`, `HHMM`, `HHMMSS[.frac]`), and
+* `T`-prefixed variants.  Calendar annotations are accepted for consistency
+* with `Temporal.PlainTime.from()` on polyfill runtimes.
+*/
+const PLAIN_TIME_RE = /* @__PURE__ */ new RegExp(`^[Tt]?(${TIME_EXTENDED}|${TIME_BASIC})${CALENDAR_ANNOTATION}$`);
+/**
+* Matches date-time strings with both date and time parts.  Accepts extended,
+* basic, and mixed forms (e.g. `2020-01-23T170436`).  The separator may be
+* `T`, `t`, or a space.  The time portion may be reduced-precision (hour
+* only).
+*/
+const PLAIN_DATETIME_RE = /* @__PURE__ */ new RegExp(`^(${DATE_EXTENDED}|${DATE_BASIC})[Tt ](${TIME_EXTENDED}|${TIME_BASIC})${CALENDAR_ANNOTATION}$`);
+/**
+* Matches YYYY-MM (extended) or YYYYMM (basic), or a full date
+* (extended or basic) with a required calendar annotation (the reference day
+* is emitted by `toString()` for non-ISO calendars).
+*/
+const PLAIN_YEAR_MONTH_RE = /* @__PURE__ */ new RegExp(`^(${YEAR}-\\d{2}(${CALENDAR_ANNOTATION}|-\\d{2}${CALENDAR_ANNOTATION_REQUIRED})|${YEAR}\\d{2}(${CALENDAR_ANNOTATION}|\\d{2}${CALENDAR_ANNOTATION_REQUIRED}))$`);
+/**
+* Matches MM-DD, --MM-DD, MMDD, or --MMDD month-day forms, or a full date
+* (extended or basic) with a required calendar annotation (the reference year
+* is emitted by `toString()` for non-ISO calendars).
+*/
+const PLAIN_MONTH_DAY_RE = /* @__PURE__ */ new RegExp(`^((--)?(\\d{2}-\\d{2}|\\d{4})${CALENDAR_ANNOTATION}|(${DATE_EXTENDED}|${DATE_BASIC})${CALENDAR_ANNOTATION_REQUIRED})$`);
+/**
 * Creates a ValueParser for parsing Temporal.PlainDate from ISO 8601 date strings.
 *
 * Accepts strings like:
@@ -164,11 +243,19 @@ function plainDate(options = {}) {
 	const metavar = options.metavar ?? "DATE";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainDate.from("1970-01-01");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_DATE_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainDate.from(input);
 				return {
 					success: true,
@@ -203,11 +290,19 @@ function plainTime(options = {}) {
 	const metavar = options.metavar ?? "TIME";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainTime.from("00:00:00");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_TIME_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainTime.from(input);
 				return {
 					success: true,
@@ -242,11 +337,19 @@ function plainDateTime(options = {}) {
 	const metavar = options.metavar ?? "DATETIME";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainDateTime.from("1970-01-01T00:00:00");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_DATETIME_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainDateTime.from(input);
 				return {
 					success: true,
@@ -281,11 +384,19 @@ function plainYearMonth(options = {}) {
 	const metavar = options.metavar ?? "YEAR-MONTH";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainYearMonth.from("1970-01");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_YEAR_MONTH_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainYearMonth.from(input);
 				return {
 					success: true,
@@ -308,8 +419,8 @@ function plainYearMonth(options = {}) {
 *
 * Accepts strings like:
 *
-* - `"--01-23"`
-* - `"--12-31"`
+* - `"01-23"`
+* - `"12-31"`
 *
 * @param options Configuration options for the plain month-day parser.
 * @returns A ValueParser that parses strings into Temporal.PlainMonthDay values.
@@ -317,14 +428,22 @@ function plainYearMonth(options = {}) {
 *   at runtime.
 */
 function plainMonthDay(options = {}) {
-	const metavar = options.metavar ?? "--MONTH-DAY";
+	const metavar = options.metavar ?? "MONTH-DAY";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainMonthDay.from("01-01");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_MONTH_DAY_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainMonthDay.from(input);
 				return {
 					success: true,
@@ -333,7 +452,7 @@ function plainMonthDay(options = {}) {
 			} catch {
 				return {
 					success: false,
-					error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : __optique_core_message.message`Invalid month-day: ${input}. Expected ISO 8601 format like ${"--01-23"}.`
+					error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : __optique_core_message.message`Invalid month-day: ${input}. Expected ISO 8601 format like ${"01-23"}.`
 				};
 			}
 		},
@@ -343,6 +462,59 @@ function plainMonthDay(options = {}) {
 	};
 }
 /**
+* Single-segment IANA timezone identifiers accepted across all supported
+* runtimes (Deno, Node.js, Bun).  This tuple is the single source of truth:
+* {@link SingleSegmentTimeZone} is derived from it, and the runtime lookup
+* {@link singleSegmentTimeZoneLookup} is built from it.
+*/
+const singleSegmentTimeZoneList = [
+	"UTC",
+	"GMT",
+	"GMT0",
+	"GMT+0",
+	"GMT-0",
+	"UCT",
+	"Universal",
+	"Greenwich",
+	"Zulu",
+	"EST",
+	"MST",
+	"HST",
+	"CET",
+	"MET",
+	"WET",
+	"EET",
+	"EST5EDT",
+	"CST6CDT",
+	"MST7MDT",
+	"PST8PDT",
+	"Cuba",
+	"Egypt",
+	"Eire",
+	"GB",
+	"GB-Eire",
+	"Hongkong",
+	"Iceland",
+	"Iran",
+	"Israel",
+	"Jamaica",
+	"Japan",
+	"Kwajalein",
+	"Libya",
+	"Navajo",
+	"NZ",
+	"NZ-CHAT",
+	"Poland",
+	"Portugal",
+	"PRC",
+	"ROC",
+	"ROK",
+	"Singapore",
+	"Turkey",
+	"W-SU"
+];
+const singleSegmentTimeZoneLookup = new Map(singleSegmentTimeZoneList.map((timeZone$1) => [timeZone$1.toLowerCase(), timeZone$1]));
+/**
 * Creates a ValueParser for parsing IANA Time Zone Database identifiers.
 *
 * Accepts strings like:
@@ -351,6 +523,8 @@ function plainMonthDay(options = {}) {
 * - `"America/New_York"`
 * - `"Europe/London"`
 * - `"UTC"`
+* - `"GMT"`
+* - `"EST"`
 *
 * @param options Configuration options for the timezone parser.
 * @returns A ValueParser that parses and validates timezone identifiers.
@@ -361,8 +535,9 @@ function timeZone(options = {}) {
 	const metavar = options.metavar ?? "TIMEZONE";
 	(0, __optique_core_nonempty.ensureNonEmptyString)(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: "UTC",
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -372,6 +547,14 @@ function timeZone(options = {}) {
 					day: 1,
 					timeZone: input
 				});
+				if (!input.includes("/")) {
+					const canonical = singleSegmentTimeZoneLookup.get(input.toLowerCase());
+					if (canonical == null) throw new RangeError();
+					return {
+						success: true,
+						value: canonical
+					};
+				}
 				return {
 					success: true,
 					value: input

package/dist/index.d.cts

@@ -11,17 +11,21 @@ import { NonEmptyString } from "@optique/core/nonempty";
  * convention:
  *
  * - Two-level: `"Asia/Seoul"`, `"America/New_York"`, `"Europe/London"`
- * - Three-level: `"America/Argentina/Buenos_Aires"`, `"America/Kentucky/Louisville"`
- * - Special case: `"UTC"`
+ * - Three-level: `"America/Argentina/Buenos_Aires"`,
+ *   `"America/Kentucky/Louisville"`
+ * - Standard single-segment: `"UTC"`, `"GMT"`, `"Universal"`
+ * - POSIX abbreviations: `"EST"`, `"CET"`, `"EST5EDT"`
+ * - Deprecated aliases: `"Japan"`, `"Singapore"`, `"Cuba"`
  *
  * @example
  * ```typescript
  * const seoul: TimeZone = "Asia/Seoul";
  * const utc: TimeZone = "UTC";
+ * const gmt: TimeZone = "GMT";
  * const buenosAires: TimeZone = "America/Argentina/Buenos_Aires";
  * ```
  */
-type TimeZone = `${string}/${string}/${string}` | `${string}/${string}` | "UTC";
+type TimeZone = `${string}/${string}/${string}` | `${string}/${string}` | SingleSegmentTimeZone;
 /**
  * Options for creating an instant parser.
  */
@@ -197,8 +201,8 @@ interface PlainMonthDayOptions {
   /**
    * The metavariable name for this parser. This is used in help messages to
    * indicate what kind of value this parser expects. Usually a single
-   * word in uppercase, like `--MONTH-DAY`.
-   * @default `"--MONTH-DAY"`
+   * word in uppercase, like `MONTH-DAY`.
+   * @default `"MONTH-DAY"`
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -342,8 +346,8 @@ declare function plainYearMonth(options?: PlainYearMonthOptions): ValueParser<"s
  *
  * Accepts strings like:
  *
- * - `"--01-23"`
- * - `"--12-31"`
+ * - `"01-23"`
+ * - `"12-31"`
  *
  * @param options Configuration options for the plain month-day parser.
  * @returns A ValueParser that parses strings into Temporal.PlainMonthDay values.
@@ -351,6 +355,14 @@ declare function plainYearMonth(options?: PlainYearMonthOptions): ValueParser<"s
  *   at runtime.
  */
 declare function plainMonthDay(options?: PlainMonthDayOptions): ValueParser<"sync", Temporal.PlainMonthDay>;
+/**
+ * Single-segment IANA timezone identifiers accepted across all supported
+ * runtimes (Deno, Node.js, Bun).  This tuple is the single source of truth:
+ * {@link SingleSegmentTimeZone} is derived from it, and the runtime lookup
+ * {@link singleSegmentTimeZoneLookup} is built from it.
+ */
+declare const singleSegmentTimeZoneList: readonly ["UTC", "GMT", "GMT0", "GMT+0", "GMT-0", "UCT", "Universal", "Greenwich", "Zulu", "EST", "MST", "HST", "CET", "MET", "WET", "EET", "EST5EDT", "CST6CDT", "MST7MDT", "PST8PDT", "Cuba", "Egypt", "Eire", "GB", "GB-Eire", "Hongkong", "Iceland", "Iran", "Israel", "Jamaica", "Japan", "Kwajalein", "Libya", "Navajo", "NZ", "NZ-CHAT", "Poland", "Portugal", "PRC", "ROC", "ROK", "Singapore", "Turkey", "W-SU"];
+type SingleSegmentTimeZone = typeof singleSegmentTimeZoneList[number];
 /**
  * Creates a ValueParser for parsing IANA Time Zone Database identifiers.
  *
@@ -360,6 +372,8 @@ declare function plainMonthDay(options?: PlainMonthDayOptions): ValueParser<"syn
  * - `"America/New_York"`
  * - `"Europe/London"`
  * - `"UTC"`
+ * - `"GMT"`
+ * - `"EST"`
  *
  * @param options Configuration options for the timezone parser.
  * @returns A ValueParser that parses and validates timezone identifiers.

package/dist/index.d.ts

@@ -12,17 +12,21 @@ import { ValueParser } from "@optique/core/valueparser";
  * convention:
  *
  * - Two-level: `"Asia/Seoul"`, `"America/New_York"`, `"Europe/London"`
- * - Three-level: `"America/Argentina/Buenos_Aires"`, `"America/Kentucky/Louisville"`
- * - Special case: `"UTC"`
+ * - Three-level: `"America/Argentina/Buenos_Aires"`,
+ *   `"America/Kentucky/Louisville"`
+ * - Standard single-segment: `"UTC"`, `"GMT"`, `"Universal"`
+ * - POSIX abbreviations: `"EST"`, `"CET"`, `"EST5EDT"`
+ * - Deprecated aliases: `"Japan"`, `"Singapore"`, `"Cuba"`
  *
  * @example
  * ```typescript
  * const seoul: TimeZone = "Asia/Seoul";
  * const utc: TimeZone = "UTC";
+ * const gmt: TimeZone = "GMT";
  * const buenosAires: TimeZone = "America/Argentina/Buenos_Aires";
  * ```
  */
-type TimeZone = `${string}/${string}/${string}` | `${string}/${string}` | "UTC";
+type TimeZone = `${string}/${string}/${string}` | `${string}/${string}` | SingleSegmentTimeZone;
 /**
  * Options for creating an instant parser.
  */
@@ -198,8 +202,8 @@ interface PlainMonthDayOptions {
   /**
    * The metavariable name for this parser. This is used in help messages to
    * indicate what kind of value this parser expects. Usually a single
-   * word in uppercase, like `--MONTH-DAY`.
-   * @default `"--MONTH-DAY"`
+   * word in uppercase, like `MONTH-DAY`.
+   * @default `"MONTH-DAY"`
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -343,8 +347,8 @@ declare function plainYearMonth(options?: PlainYearMonthOptions): ValueParser<"s
  *
  * Accepts strings like:
  *
- * - `"--01-23"`
- * - `"--12-31"`
+ * - `"01-23"`
+ * - `"12-31"`
  *
  * @param options Configuration options for the plain month-day parser.
  * @returns A ValueParser that parses strings into Temporal.PlainMonthDay values.
@@ -352,6 +356,14 @@ declare function plainYearMonth(options?: PlainYearMonthOptions): ValueParser<"s
  *   at runtime.
  */
 declare function plainMonthDay(options?: PlainMonthDayOptions): ValueParser<"sync", Temporal.PlainMonthDay>;
+/**
+ * Single-segment IANA timezone identifiers accepted across all supported
+ * runtimes (Deno, Node.js, Bun).  This tuple is the single source of truth:
+ * {@link SingleSegmentTimeZone} is derived from it, and the runtime lookup
+ * {@link singleSegmentTimeZoneLookup} is built from it.
+ */
+declare const singleSegmentTimeZoneList: readonly ["UTC", "GMT", "GMT0", "GMT+0", "GMT-0", "UCT", "Universal", "Greenwich", "Zulu", "EST", "MST", "HST", "CET", "MET", "WET", "EET", "EST5EDT", "CST6CDT", "MST7MDT", "PST8PDT", "Cuba", "Egypt", "Eire", "GB", "GB-Eire", "Hongkong", "Iceland", "Iran", "Israel", "Jamaica", "Japan", "Kwajalein", "Libya", "Navajo", "NZ", "NZ-CHAT", "Poland", "Portugal", "PRC", "ROC", "ROK", "Singapore", "Turkey", "W-SU"];
+type SingleSegmentTimeZone = typeof singleSegmentTimeZoneList[number];
 /**
  * Creates a ValueParser for parsing IANA Time Zone Database identifiers.
  *
@@ -361,6 +373,8 @@ declare function plainMonthDay(options?: PlainMonthDayOptions): ValueParser<"syn
  * - `"America/New_York"`
  * - `"Europe/London"`
  * - `"UTC"`
+ * - `"GMT"`
+ * - `"EST"`
  *
  * @param options Configuration options for the timezone parser.
  * @returns A ValueParser that parses and validates timezone identifiers.

package/dist/index.js

@@ -23,8 +23,15 @@ function instant(options = {}) {
 	const metavar = options.metavar ?? "TIMESTAMP";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.Instant.from("1970-01-01T00:00:00Z");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -63,8 +70,15 @@ function duration(options = {}) {
 	const metavar = options.metavar ?? "DURATION";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.Duration.from("PT0S");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -102,8 +116,15 @@ function zonedDateTime(options = {}) {
 	const metavar = options.metavar ?? "ZONED_DATETIME";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.ZonedDateTime.from("1970-01-01T00:00:00+00:00[UTC]");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -125,6 +146,64 @@ function zonedDateTime(options = {}) {
 	};
 }
 /**
+* Optional RFC 9557 calendar annotation suffix, e.g. `[u-ca=gregory]`.
+* Accepts case-insensitive values and the optional critical flag (`!`).
+* Used by all plain Temporal regexes to accept `toString()` output for
+* non-ISO calendars.
+*/
+const CALENDAR_ANNOTATION = String.raw`(\[!?u-ca=[a-zA-Z0-9\-]+\])?`;
+/**
+* Required RFC 9557 calendar annotation (non-optional variant used when the
+* annotation must be present, e.g. for reference-day/year forms).
+*/
+const CALENDAR_ANNOTATION_REQUIRED = String.raw`\[!?u-ca=[a-zA-Z0-9\-]+\]`;
+/**
+* Year portion: either 4 digits (`YYYY`) or a sign-prefixed 6-digit expanded
+* year (`+YYYYYY` / `-YYYYYY`).
+*/
+const YEAR = String.raw`([+-]\d{6}|\d{4})`;
+/** ISO 8601 fractional seconds with `.` or `,` separator. */
+const FRACTIONAL = String.raw`[.,]\d+`;
+/** Extended date: `YYYY-MM-DD` or `±YYYYYY-MM-DD`. */
+const DATE_EXTENDED = `${YEAR}-\\d{2}-\\d{2}`;
+/** Basic date: `YYYYMMDD` or `±YYYYYYMMDD`. */
+const DATE_BASIC = `${YEAR}\\d{4}`;
+/** Extended time: `HH:MM[:SS[.frac]]`. */
+const TIME_EXTENDED = `\\d{2}:\\d{2}(:\\d{2}(${FRACTIONAL})?)?`;
+/** Basic time: `HH`, `HHMM`, or `HHMMSS[.frac]`. */
+const TIME_BASIC = `\\d{2}(\\d{2}(\\d{2}(${FRACTIONAL})?)?)?`;
+/**
+* Matches YYYY-MM-DD (extended) or YYYYMMDD (basic) date forms only (no time
+* component).  Both forms accept expanded years and calendar annotations.
+*/
+const PLAIN_DATE_RE = /* @__PURE__ */ new RegExp(`^(${DATE_EXTENDED}|${DATE_BASIC})${CALENDAR_ANNOTATION}$`);
+/**
+* Matches time forms only (no date prefix).  Accepts extended
+* (`HH:MM[:SS[.frac]]`), basic (`HH`, `HHMM`, `HHMMSS[.frac]`), and
+* `T`-prefixed variants.  Calendar annotations are accepted for consistency
+* with `Temporal.PlainTime.from()` on polyfill runtimes.
+*/
+const PLAIN_TIME_RE = /* @__PURE__ */ new RegExp(`^[Tt]?(${TIME_EXTENDED}|${TIME_BASIC})${CALENDAR_ANNOTATION}$`);
+/**
+* Matches date-time strings with both date and time parts.  Accepts extended,
+* basic, and mixed forms (e.g. `2020-01-23T170436`).  The separator may be
+* `T`, `t`, or a space.  The time portion may be reduced-precision (hour
+* only).
+*/
+const PLAIN_DATETIME_RE = /* @__PURE__ */ new RegExp(`^(${DATE_EXTENDED}|${DATE_BASIC})[Tt ](${TIME_EXTENDED}|${TIME_BASIC})${CALENDAR_ANNOTATION}$`);
+/**
+* Matches YYYY-MM (extended) or YYYYMM (basic), or a full date
+* (extended or basic) with a required calendar annotation (the reference day
+* is emitted by `toString()` for non-ISO calendars).
+*/
+const PLAIN_YEAR_MONTH_RE = /* @__PURE__ */ new RegExp(`^(${YEAR}-\\d{2}(${CALENDAR_ANNOTATION}|-\\d{2}${CALENDAR_ANNOTATION_REQUIRED})|${YEAR}\\d{2}(${CALENDAR_ANNOTATION}|\\d{2}${CALENDAR_ANNOTATION_REQUIRED}))$`);
+/**
+* Matches MM-DD, --MM-DD, MMDD, or --MMDD month-day forms, or a full date
+* (extended or basic) with a required calendar annotation (the reference year
+* is emitted by `toString()` for non-ISO calendars).
+*/
+const PLAIN_MONTH_DAY_RE = /* @__PURE__ */ new RegExp(`^((--)?(\\d{2}-\\d{2}|\\d{4})${CALENDAR_ANNOTATION}|(${DATE_EXTENDED}|${DATE_BASIC})${CALENDAR_ANNOTATION_REQUIRED})$`);
+/**
 * Creates a ValueParser for parsing Temporal.PlainDate from ISO 8601 date strings.
 *
 * Accepts strings like:
@@ -141,11 +220,19 @@ function plainDate(options = {}) {
 	const metavar = options.metavar ?? "DATE";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainDate.from("1970-01-01");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_DATE_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainDate.from(input);
 				return {
 					success: true,
@@ -180,11 +267,19 @@ function plainTime(options = {}) {
 	const metavar = options.metavar ?? "TIME";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainTime.from("00:00:00");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_TIME_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainTime.from(input);
 				return {
 					success: true,
@@ -219,11 +314,19 @@ function plainDateTime(options = {}) {
 	const metavar = options.metavar ?? "DATETIME";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainDateTime.from("1970-01-01T00:00:00");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_DATETIME_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainDateTime.from(input);
 				return {
 					success: true,
@@ -258,11 +361,19 @@ function plainYearMonth(options = {}) {
 	const metavar = options.metavar ?? "YEAR-MONTH";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainYearMonth.from("1970-01");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_YEAR_MONTH_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainYearMonth.from(input);
 				return {
 					success: true,
@@ -285,8 +396,8 @@ function plainYearMonth(options = {}) {
 *
 * Accepts strings like:
 *
-* - `"--01-23"`
-* - `"--12-31"`
+* - `"01-23"`
+* - `"12-31"`
 *
 * @param options Configuration options for the plain month-day parser.
 * @returns A ValueParser that parses strings into Temporal.PlainMonthDay values.
@@ -294,14 +405,22 @@ function plainYearMonth(options = {}) {
 *   at runtime.
 */
 function plainMonthDay(options = {}) {
-	const metavar = options.metavar ?? "--MONTH-DAY";
+	const metavar = options.metavar ?? "MONTH-DAY";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			try {
+				return Temporal.PlainMonthDay.from("01-01");
+			} catch {
+				return void 0;
+			}
+		},
 		parse(input) {
 			ensureTemporal();
 			try {
+				if (!PLAIN_MONTH_DAY_RE.test(input)) throw new RangeError();
 				const value = Temporal.PlainMonthDay.from(input);
 				return {
 					success: true,
@@ -310,7 +429,7 @@ function plainMonthDay(options = {}) {
 			} catch {
 				return {
 					success: false,
-					error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : message`Invalid month-day: ${input}. Expected ISO 8601 format like ${"--01-23"}.`
+					error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : message`Invalid month-day: ${input}. Expected ISO 8601 format like ${"01-23"}.`
 				};
 			}
 		},
@@ -320,6 +439,59 @@ function plainMonthDay(options = {}) {
 	};
 }
 /**
+* Single-segment IANA timezone identifiers accepted across all supported
+* runtimes (Deno, Node.js, Bun).  This tuple is the single source of truth:
+* {@link SingleSegmentTimeZone} is derived from it, and the runtime lookup
+* {@link singleSegmentTimeZoneLookup} is built from it.
+*/
+const singleSegmentTimeZoneList = [
+	"UTC",
+	"GMT",
+	"GMT0",
+	"GMT+0",
+	"GMT-0",
+	"UCT",
+	"Universal",
+	"Greenwich",
+	"Zulu",
+	"EST",
+	"MST",
+	"HST",
+	"CET",
+	"MET",
+	"WET",
+	"EET",
+	"EST5EDT",
+	"CST6CDT",
+	"MST7MDT",
+	"PST8PDT",
+	"Cuba",
+	"Egypt",
+	"Eire",
+	"GB",
+	"GB-Eire",
+	"Hongkong",
+	"Iceland",
+	"Iran",
+	"Israel",
+	"Jamaica",
+	"Japan",
+	"Kwajalein",
+	"Libya",
+	"Navajo",
+	"NZ",
+	"NZ-CHAT",
+	"Poland",
+	"Portugal",
+	"PRC",
+	"ROC",
+	"ROK",
+	"Singapore",
+	"Turkey",
+	"W-SU"
+];
+const singleSegmentTimeZoneLookup = new Map(singleSegmentTimeZoneList.map((timeZone$1) => [timeZone$1.toLowerCase(), timeZone$1]));
+/**
 * Creates a ValueParser for parsing IANA Time Zone Database identifiers.
 *
 * Accepts strings like:
@@ -328,6 +500,8 @@ function plainMonthDay(options = {}) {
 * - `"America/New_York"`
 * - `"Europe/London"`
 * - `"UTC"`
+* - `"GMT"`
+* - `"EST"`
 *
 * @param options Configuration options for the timezone parser.
 * @returns A ValueParser that parses and validates timezone identifiers.
@@ -338,8 +512,9 @@ function timeZone(options = {}) {
 	const metavar = options.metavar ?? "TIMEZONE";
 	ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: "UTC",
 		parse(input) {
 			ensureTemporal();
 			try {
@@ -349,6 +524,14 @@ function timeZone(options = {}) {
 					day: 1,
 					timeZone: input
 				});
+				if (!input.includes("/")) {
+					const canonical = singleSegmentTimeZoneLookup.get(input.toLowerCase());
+					if (canonical == null) throw new RangeError();
+					return {
+						success: true,
+						value: canonical
+					};
+				}
 				return {
 					success: true,
 					value: input

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/temporal",
-  "version": "1.0.0-dev.921+754748bd",
+  "version": "1.0.0",
   "description": "Temporal value parsers for Optique",
   "keywords": [
     "CLI",
@@ -56,7 +56,7 @@
   "sideEffects": false,
   "dependencies": {
     "@js-temporal/polyfill": "^0.5.1",
-    "@optique/core": "1.0.0-dev.921+754748bd"
+    "@optique/core": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",