@northguild/gmt 1.17.0 → 1.19.0

package/dist/plain/calculate/cycleDate.js

@@ -12,24 +12,20 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   overflow into January of the *next* year. Reach for `addDate` when you want calendar
  *   arithmetic; reach for `cycleDate` when a single field (e.g. a datepicker segment) must stay
  *   isolated from the others.
- * - `year` has no upper/lower wrap — cycling it is plain addition (or rounding, see below).
+ * - `year` has no upper/lower wrap — cycling it is plain addition (or a step to a multiple, with
+ *   `round`): `2022` by `+5` with `round: true` lands on `2025`, the next multiple of 5.
  *   `month` wraps `1–12`. `day` wraps `1`–the **current** month's day count, so cycling `day`
  *   never changes `month`.
  * - Cycling `month` or `year` can still shift `day` via `overflow` — e.g. cycling `month` from a
  *   31st into a shorter month clamps under the default `"constrain"` (or returns `""` under
  *   `"reject"`) exactly the way `setDate`'s own `.with()` call does; this is the same clamping
  *   `addDate`'s Jan 31 + 1 month case produces, not new behavior.
- * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
- *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
- *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling `year` `2022` by `+5` with
- *   `round: true` lands on `2025` (the next multiple of 5 above 2022), not `2020` (the nearest
- *   multiple).
  * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDate string
  * @param field the field to cycle: "year" | "month" | "day"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @param options How the field is stepped and an out-of-range day is handled
  * @returns ISO PlainDate string with `field` cycled, or "" on invalid input
  *
  * @example cycleDate("2024-06-15", "month", 1) // "2024-07-15"

package/dist/plain/calculate/cycleDateTime.d.ts

@@ -14,15 +14,12 @@ import type { DateTimeCycleField, Overflow } from "../../types/index.js";
  *   why).
  * - Cycling `month` or `year` can still shift `day` via `overflow`, exactly as `setDateTime`'s
  *   `.with()` call does.
- * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
- *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
- *   docs for worked examples.
  * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDateTime string
  * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @param options How the field is stepped and an out-of-range day is handled
  * @returns ISO PlainDateTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleDateTime("2024-06-15T09:30:00", "hour", 1) // "2024-06-15T10:30:00"
@@ -33,6 +30,19 @@ import type { DateTimeCycleField, Overflow } from "../../types/index.js";
  * @example cycleDateTime("invalid", "hour", 1) // ""
  */
 export declare function cycleDateTime(value: string, field: DateTimeCycleField, amount: number, options?: {
+    /**
+     * Whether to step to a multiple of `amount` instead of adding it. `true` moves to the next
+     * multiple in the direction of the sign of `amount` (the ceiling for a positive amount, the
+     * floor for a negative one), not to the nearest one; `false` adds `amount`.
+     *
+     * @defaultValue `false`
+     */
     round?: boolean;
+    /**
+     * What to do when the cycled `month` or `year` leaves `day` past the end of its month.
+     * `"constrain"` clamps `day` to the last day of that month; `"reject"` returns `""`.
+     *
+     * @defaultValue `"constrain"`, Temporal's default.
+     */
     overflow?: Overflow;
 }): string;

package/dist/plain/calculate/cycleDateTime.js

@@ -18,15 +18,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   why).
  * - Cycling `month` or `year` can still shift `day` via `overflow`, exactly as `setDateTime`'s
  *   `.with()` call does.
- * - `options.round` steps to the *next* multiple of `amount` in the direction of its sign
- *   (ceiling for positive, floor for negative) — not the nearest one. See `cycleDate`/`cycleTime`'s
- *   docs for worked examples.
  * - Returns "" for an invalid `value`, an invalid `field`, or an `amount` that is not a finite number.
  *
  * @param value ISO PlainDateTime string
  * @param field the field to cycle: "year" | "month" | "day" | "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false), overflow ("constrain" | "reject")
+ * @param options How the field is stepped and an out-of-range day is handled
  * @returns ISO PlainDateTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleDateTime("2024-06-15T09:30:00", "hour", 1) // "2024-06-15T10:30:00"

package/dist/plain/calculate/cycleTime.d.ts

@@ -9,10 +9,8 @@ import type { TimeCycleField } from "../../types/index.js";
  *   is no ISO representation for "this hour, but staying AM" to round-trip through GMT's string
  *   contract.
  * - `minute`/`second` wrap `0–59`; `millisecond`/`microsecond`/`nanosecond` wrap `0–999`.
- * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
- *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
- *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling minute `22` by `+15` with
- *   `round: true` lands on `30` (the next multiple of 15 above 22), not `15` (the nearest one).
+ * - With `round: true`, minute `22` by `+15` lands on `30`, the next multiple of 15 above 22, not
+ *   on `15`, the nearest one.
  * - There is no `overflow` option (removed in 1.16.0): time fields don't share bounds the way `day`
  *   shares a month with `month`/`year`, so the wrapped value is always already valid and there is
  *   nothing to constrain or reject.
@@ -21,7 +19,7 @@ import type { TimeCycleField } from "../../types/index.js";
  * @param value ISO PlainTime string
  * @param field the field to cycle: "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false)
+ * @param options How the field is stepped
  * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"
@@ -32,5 +30,12 @@ import type { TimeCycleField } from "../../types/index.js";
  * @example cycleTime("invalid", "hour", 1) // ""
  */
 export declare function cycleTime(value: string, field: TimeCycleField, amount: number, options?: {
+    /**
+     * Whether to step to a multiple of `amount` instead of adding it. `true` moves to the next
+     * multiple in the direction of the sign of `amount` (the ceiling for a positive amount, the
+     * floor for a negative one), not to the nearest one; `false` adds `amount`.
+     *
+     * @defaultValue `false`
+     */
     round?: boolean;
 }): string;

package/dist/plain/calculate/cycleTime.js

@@ -13,10 +13,8 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   is no ISO representation for "this hour, but staying AM" to round-trip through GMT's string
  *   contract.
  * - `minute`/`second` wrap `0–59`; `millisecond`/`microsecond`/`nanosecond` wrap `0–999`.
- * - `options.round` does **not** round to the nearest increment — it steps to the *next* multiple
- *   of `amount` in the direction of its sign (ceiling for positive, floor for negative), matching
- *   `@internationalized/date`'s `CycleOptions.round`. E.g. cycling minute `22` by `+15` with
- *   `round: true` lands on `30` (the next multiple of 15 above 22), not `15` (the nearest one).
+ * - With `round: true`, minute `22` by `+15` lands on `30`, the next multiple of 15 above 22, not
+ *   on `15`, the nearest one.
  * - There is no `overflow` option (removed in 1.16.0): time fields don't share bounds the way `day`
  *   shares a month with `month`/`year`, so the wrapped value is always already valid and there is
  *   nothing to constrain or reject.
@@ -25,7 +23,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param value ISO PlainTime string
  * @param field the field to cycle: "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
  * @param amount signed amount to cycle by
- * @param options optional: round (boolean, default false)
+ * @param options How the field is stepped
  * @returns ISO PlainTime string with `field` cycled, or "" on invalid input
  *
  * @example cycleTime("09:30:00", "hour", 1) // "10:30:00"

package/dist/plain/calculate/diffDate.d.ts

@@ -34,7 +34,7 @@ import type { DateDurationUnit, RoundingOptions } from "../../types/index.js";
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unitArg date unit or units to measure the difference, singular or plural (`"day"` or
  *   `"days"`); a record result keeps the plural keys
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDate("2024-03-10", "2024-03-15", "days") // 5

package/dist/plain/calculate/diffDate.js

@@ -38,7 +38,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unitArg date unit or units to measure the difference, singular or plural (`"day"` or
  *   `"days"`); a record result keeps the plural keys
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDate("2024-03-10", "2024-03-15", "days") // 5

package/dist/plain/calculate/diffDateAsDuration.d.ts

@@ -27,7 +27,7 @@ import type { DateDurationUnit, DurationStringOptions, RoundingOptions } from ".
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unit date unit, singular or plural (`"day"` or `"days"`), to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"

package/dist/plain/calculate/diffDateAsDuration.js

@@ -29,7 +29,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param date1 ISO PlainDate string for the start, optionally calendar-annotated
  * @param date2 ISO PlainDate string for the end, optionally calendar-annotated
  * @param unit date unit, singular or plural (`"day"` or `"days"`), to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateAsDuration("2024-03-10", "2024-04-05", "days") // "P26D"

package/dist/plain/calculate/diffDateTime.d.ts

@@ -27,7 +27,7 @@ import type { DateTimeDurationUnit, RoundingOptions } from "../../types/index.js
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "days") // 5

package/dist/plain/calculate/diffDateTime.js

@@ -33,7 +33,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param units DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "days") // 5

package/dist/plain/calculate/diffDateTimeAsDuration.d.ts

@@ -21,7 +21,7 @@ import type { DateTimeDurationUnit, DurationStringOptions, RoundingOptions } fro
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"

package/dist/plain/calculate/diffDateTimeAsDuration.js

@@ -24,7 +24,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param dateTime1 ISO PlainDateTime string for the start
  * @param dateTime2 ISO PlainDateTime string for the end
  * @param unit DateTimeDurationUnit to use as the duration's largestUnit
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded and how the string is rendered; a non-object value (such as `null`) is invalid
  * @returns ISO 8601 duration string, or "" on invalid input
  *
  * @example diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"

package/dist/plain/calculate/diffTime.d.ts

@@ -28,7 +28,7 @@ import type { RoundingOptions, TimeDurationUnit } from "../../types/index.js";
  * @param time1 ISO PlainTime string for the start
  * @param time2 ISO PlainTime string for the end
  * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffTime("12:00:00", "14:30:00", "hours") // 2

package/dist/plain/calculate/diffTime.js

@@ -33,7 +33,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @param time1 ISO PlainTime string for the start
  * @param time2 ISO PlainTime string for the end
  * @param units TimeDurationUnit | TimeDurationUnit[] to measure the difference
- * @param options optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls); a non-object value (such as `null`) is invalid
+ * @param options optional: how the difference is rounded; a non-object value (such as `null`) is invalid
  * @returns numeric difference in the requested unit, or null on invalid input
  *
  * @example diffTime("12:00:00", "14:30:00", "hours") // 2

package/dist/plain/calculate/endOfDate.d.ts

@@ -2,16 +2,14 @@ import { Temporal } from "@js-temporal/polyfill";
 /**
  * Return the end of the specified date `unit` for a given ISO 8601 date string.
  *
- * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
  * - The end is computed forward from `value`, so it is returned even when the unit began before
  *   the first representable date (`-271821-04-19`).
  * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  *
  * @param value ISO 8601 date string
  * @param unit date unit, singular or plural, to specify the unit for the end
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDate("2024-02-29", "month") // "2024-02-29"
@@ -21,5 +19,12 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example endOfDate("invalid-date", "month") // ""
  */
 export declare function endOfDate(value: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
 }): string;

package/dist/plain/calculate/endOfDate.js

@@ -8,16 +8,14 @@ const supported = ["year", "month", "week", "day"];
 /**
  * Return the end of the specified date `unit` for a given ISO 8601 date string.
  *
- * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
  * - The end is computed forward from `value`, so it is returned even when the unit began before
  *   the first representable date (`-271821-04-19`).
  * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  *
  * @param value ISO 8601 date string
  * @param unit date unit, singular or plural, to specify the unit for the end
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
+ * @param optionsArg How the week is defined
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDate("2024-02-29", "month") // "2024-02-29"

package/dist/plain/calculate/endOfDateTime.d.ts

@@ -3,13 +3,9 @@ import type { FractionalDigit } from "../../types/index.js";
 /**
  * Return the end of the specified date-time `unit` for a given ISO 8601 datetime string.
  *
- * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
  * - The end is computed forward from `value`, so it is returned even when the unit began before
  *   the first representable date (`-271821-04-19`).
- * - The end is written at nanosecond precision by default, so the string names the end itself; an
- *   explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
  *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
@@ -17,7 +13,7 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * @param value ISO 8601 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the end
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param optionsArg How the week is defined and how the result is written
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-29T23:59:59.999999999"
@@ -29,6 +25,20 @@ import type { FractionalDigit } from "../../types/index.js";
  * @example endOfDateTime("invalid-date", "month") // ""
  */
 export declare function endOfDateTime(value: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, optionsArg?: {
+    /**
+     * The first day of the week, which sets where a `"week"` unit starts. `"monday"` is the ISO
+     * 8601 week, Monday to Sunday; `"sunday"` runs Sunday to Saturday. Any other value returns
+     * `""`, whatever the unit.
+     *
+     * @defaultValue `"monday"`
+     */
     weekStartsOn?: "monday" | "sunday";
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer than 9 digits truncate the string, as Temporal's `toString` does,
+     * so it names a moment before the end.
+     *
+     * @defaultValue `9`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/plain/calculate/endOfDateTime.js

@@ -19,13 +19,9 @@ const supported = [
 /**
  * Return the end of the specified date-time `unit` for a given ISO 8601 datetime string.
  *
- * - A Sunday-first week runs Sunday to Saturday, so a Sunday ends its week six days later.
  * - The end is computed forward from `value`, so it is returned even when the unit began before
  *   the first representable date (`-271821-04-19`).
- * - The end is written at nanosecond precision by default, so the string names the end itself; an
- *   explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
- * - `weekStartsOn` other than `"monday"` or `"sunday"` returns "".
  * - Returns "" for invalid inputs.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
  *   `second` and coarser, 3 for `millisecond`, 6 for `microsecond` — which wrote a moment earlier
@@ -33,7 +29,7 @@ const supported = [
  *
  * @param value ISO 8601 datetime string
  * @param unit date or time unit, singular or plural, to specify the unit for the end
- * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @param optionsArg How the week is defined and how the result is written
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfDateTime("2024-02-29T12:34:56", "month") // "2024-02-29T23:59:59.999999999"

package/dist/plain/calculate/endOfTime.d.ts

@@ -8,11 +8,10 @@ import type { FractionalDigit } from "../../types/index.js";
  * import { EndOfTimeUnit } from "@northguild/gmt/plain";
  * const unit: EndOfTimeUnit = "minutes";
  */
-export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
+export type EndOfTimeUnit = Temporal.SmallestUnit<"day" | Temporal.TimeUnit>;
 /**
  * Return the end of the specified time `unit` for a given ISO 8601 time string.
  *
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid inputs.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
@@ -21,7 +20,7 @@ export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
  *
  * @param value ISO 8601 time string
  * @param unit EndOfTimeUnit to specify the unit for the end
- * @param optionsArg optional: fractionalSecondDigits (number)
+ * @param optionsArg How the result is written
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfTime("12:34:56", "hour") // "12:59:59.999999999"
@@ -30,5 +29,12 @@ export type EndOfTimeUnit = Temporal.SmallestUnit<Temporal.TimeUnit | "day">;
  * @example endOfTime("invalid", "hour") // ""
  */
 export declare function endOfTime(value: string, unit: EndOfTimeUnit, optionsArg?: {
+    /**
+     * The number of fractional-second digits the result is written with, `0` to `9`, or `"auto"` to
+     * drop trailing zeros. Fewer than 9 digits truncate the string, as Temporal's `toString` does,
+     * so it names a moment before the end.
+     *
+     * @defaultValue `9`
+     */
     fractionalSecondDigits?: FractionalDigit;
 }): string;

package/dist/plain/calculate/endOfTime.js

@@ -15,7 +15,6 @@ const supported = [
 /**
  * Return the end of the specified time `unit` for a given ISO 8601 time string.
  *
- * - The end is written at nanosecond precision by default, so the string names the end itself; an explicit `fractionalSecondDigits` (0, 3, 6 or 9) truncates it, as Temporal's `toString` does.
  * - `unit` accepts the singular or plural name (`"hour"` or `"hours"`), as Temporal does.
  * - Returns "" for invalid inputs.
  * - **Compatibility:** before 1.16.0 the default printed only the digits the unit names — none for
@@ -24,7 +23,7 @@ const supported = [
  *
  * @param value ISO 8601 time string
  * @param unit EndOfTimeUnit to specify the unit for the end
- * @param optionsArg optional: fractionalSecondDigits (number)
+ * @param optionsArg How the result is written
  * @returns ISO 8601 string representing the end of the specified unit, or "" on invalid input
  *
  * @example endOfTime("12:34:56", "hour") // "12:59:59.999999999"

package/dist/plain/calculate/getLocaleWeekYear.d.ts

@@ -7,21 +7,21 @@
  * - Week 1 is the week starting on `locale`'s first day of week that holds at least `minimalDays`
  *   days of January (UTS #35 Part 4, Week Data). The first day of week comes from
  *   `Intl.Locale.prototype.getWeekInfo`.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days: Intl Locale Info returns only `firstDay` and `weekend`
- *   (tc39/proposal-intl-locale-info#86), so older runtimes that still reported it disagreed with
- *   newer ones about the same date. Pass CLDR's value when you need a locale's own rule: in CLDR 48
- *   `weekData`, the world default (`001`) is `1` — week 1 always contains January 1, as in `US`,
- *   `CA`, `MX`, `JP` and `CN` — and `4` is set for a list of mostly European regions such as `GB`,
- *   `DE` and `FR`, where it matches this default.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime, so one input has one answer
+ *   everywhere. ECMA-402 does not expose a locale's minimal days: Intl Locale Info returns only
+ *   `firstDay` and `weekend` (tc39/proposal-intl-locale-info#86), so older runtimes that still
+ *   reported it disagreed with newer ones about the same date. Pass CLDR's value when you need a
+ *   locale's own rule: in CLDR 48 `weekData`, the world default (`001`) is `1`, as in `US`, `CA`,
+ *   `MX`, `JP` and `CN`, and `4` is set for a list of mostly European regions such as `GB`, `DE`
+ *   and `FR`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns locale-relative week-numbering year, or null on invalid input
  *
  * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024
@@ -34,5 +34,12 @@
  * @example getLocaleWeekYear("2024-12-29", ["en-US", "fr-FR"]) // 2025
  */
 export declare function getLocaleWeekYear(value: string, locale: string | string[], options?: {
+    /**
+     * How many days of January the first week must hold to be week 1 (UTS #35 Part 4, Week
+     * Data). `4` is the ISO 8601 rule; `1` puts January 1 in week 1 every year, as CLDR's world
+     * default does. A value that is not an integer from 1 to 7 returns `null`.
+     *
+     * @defaultValue `4`
+     */
     minimalDays?: number;
 }): number | null;

package/dist/plain/calculate/getLocaleWeekYear.js

@@ -12,21 +12,21 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Week 1 is the week starting on `locale`'s first day of week that holds at least `minimalDays`
  *   days of January (UTS #35 Part 4, Week Data). The first day of week comes from
  *   `Intl.Locale.prototype.getWeekInfo`.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days: Intl Locale Info returns only `firstDay` and `weekend`
- *   (tc39/proposal-intl-locale-info#86), so older runtimes that still reported it disagreed with
- *   newer ones about the same date. Pass CLDR's value when you need a locale's own rule: in CLDR 48
- *   `weekData`, the world default (`001`) is `1` — week 1 always contains January 1, as in `US`,
- *   `CA`, `MX`, `JP` and `CN` — and `4` is set for a list of mostly European regions such as `GB`,
- *   `DE` and `FR`, where it matches this default.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime, so one input has one answer
+ *   everywhere. ECMA-402 does not expose a locale's minimal days: Intl Locale Info returns only
+ *   `firstDay` and `weekend` (tc39/proposal-intl-locale-info#86), so older runtimes that still
+ *   reported it disagreed with newer ones about the same date. Pass CLDR's value when you need a
+ *   locale's own rule: in CLDR 48 `weekData`, the world default (`001`) is `1`, as in `US`, `CA`,
+ *   `MX`, `JP` and `CN`, and `4` is set for a list of mostly European regions such as `GB`, `DE`
+ *   and `FR`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns locale-relative week-numbering year, or null on invalid input
  *
  * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024

package/dist/plain/calculate/getWeekOfMonth.d.ts

@@ -3,10 +3,13 @@
  * grid, using `locale`'s first day of week.
  *
  * - Week 1 is the row containing the 1st of the month, even when that row
- *   is a partial week (matches date-fns's `getWeekOfMonth`, verified
- *   against date-fns source 2026-08-21) — this is the convention every
- *   calendar-grid UI (and `@internationalized/date`'s `getWeeksInMonth`)
- *   expects for sizing a month grid.
+ *   is a partial week. This is GMT's own rule, not a standard's: a month
+ *   grid draws every day of the month, so its first row always holds the 1st.
+ * - Not CLDR's week-of-month field (`W`, UTS #35): that count applies the
+ *   locale's `minDays`, so a short leading week may not count as part of
+ *   the month.
+ * - Comparison: date-fns's `getWeekOfMonth` returns the same number for the
+ *   same first day of week.
  * - Distinct from ISO `weekOfYear`: this counts rows within a single
  *   month's grid, reset every month, rather than weeks since Jan 1.
  * - Resolves the locale's first day of week via

package/dist/plain/calculate/getWeekOfMonth.js

@@ -7,10 +7,13 @@ import { isValidDate } from "../validate/index.js";
  * grid, using `locale`'s first day of week.
  *
  * - Week 1 is the row containing the 1st of the month, even when that row
- *   is a partial week (matches date-fns's `getWeekOfMonth`, verified
- *   against date-fns source 2026-08-21) — this is the convention every
- *   calendar-grid UI (and `@internationalized/date`'s `getWeeksInMonth`)
- *   expects for sizing a month grid.
+ *   is a partial week. This is GMT's own rule, not a standard's: a month
+ *   grid draws every day of the month, so its first row always holds the 1st.
+ * - Not CLDR's week-of-month field (`W`, UTS #35): that count applies the
+ *   locale's `minDays`, so a short leading week may not count as part of
+ *   the month.
+ * - Comparison: date-fns's `getWeekOfMonth` returns the same number for the
+ *   same first day of week.
  * - Distinct from ISO `weekOfYear`: this counts rows within a single
  *   month's grid, reset every month, rather than weeks since Jan 1.
  * - Resolves the locale's first day of week via

package/dist/plain/calculate/getWeeksInLocaleWeekYear.d.ts

@@ -7,18 +7,18 @@
  * - Computed as the calendar days between this week-year's start and the next one's, divided by 7 —
  *   always whole, since both starts fall on the locale's first day of week. Counted by day
  *   arithmetic, so a start outside the representable range still counts.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
- *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when it
- *   differs. See `getLocaleWeekYear`.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime: ECMA-402 does not expose a
+ *   locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
+ *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when you
+ *   need its own rule. See `getLocaleWeekYear`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns 52 or 53, or null on invalid input
  *
  * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52
@@ -31,5 +31,12 @@
  * @example getWeeksInLocaleWeekYear("2024-12-29", ["fr-FR", "en-US"]) // 52
  */
 export declare function getWeeksInLocaleWeekYear(value: string, locale: string | string[], options?: {
+    /**
+     * How many days of January the first week must hold to be week 1 (UTS #35 Part 4, Week
+     * Data). `4` is the ISO 8601 rule; `1` puts January 1 in week 1 every year, as CLDR's world
+     * default does. A value that is not an integer from 1 to 7 returns `null`.
+     *
+     * @defaultValue `4`
+     */
     minimalDays?: number;
 }): number | null;

package/dist/plain/calculate/getWeeksInLocaleWeekYear.js

@@ -12,18 +12,18 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Computed as the calendar days between this week-year's start and the next one's, divided by 7 —
  *   always whole, since both starts fall on the locale's first day of week. Counted by day
  *   arithmetic, so a start outside the representable range still counts.
- * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
- *   a locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
- *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when it
- *   differs. See `getLocaleWeekYear`.
- * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - The minimal-days rule comes from the caller, never the runtime: ECMA-402 does not expose a
+ *   locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
+ *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when you
+ *   need its own rule. See `getLocaleWeekYear`.
+ * - Returns null if `value` or `locale` is invalid.
  * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
  *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
  *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
  * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null
- * @param options optional: minimalDays (integer 1–7, default 4)
+ * @param options The minimal-days-in-first-week rule
  * @returns 52 or 53, or null on invalid input
  *
  * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52