Move DateDurationUnit to options, document weeks behavior (#7732) This is an option, it should be in options. "weeks" is interesting since it is not possible to get weeks out of `until` _unless_ you specifically ask for them. I've documented this on DateDifferenceOptions. We could also document it on DateDurationUnit.

diff --git a/components/calendar/benches/until.rs b/components/calendar/benches/until.rs
index 063de0e..cad41b2 100644
--- a/components/calendar/benches/until.rs
+++ b/components/calendar/benches/until.rs

@@ -5,8 +5,8 @@
 use criterion::{
     black_box, criterion_group, criterion_main, measurement::WallTime, BenchmarkGroup, Criterion,
 };
-use icu_calendar::options::DateDifferenceOptions;
-use icu_calendar::types::{DateDurationUnit, RataDie};
+use icu_calendar::options::{DateDifferenceOptions, DateDurationUnit};
+use icu_calendar::types::RataDie;
 use icu_calendar::{Calendar, Date};
 
 #[macro_use]

diff --git a/components/calendar/fuzz/fuzz_targets/until.rs b/components/calendar/fuzz/fuzz_targets/until.rs
index bc0c140..60eb617 100644
--- a/components/calendar/fuzz/fuzz_targets/until.rs
+++ b/components/calendar/fuzz/fuzz_targets/until.rs

@@ -28,7 +28,7 @@
     Days,
 }
 
-impl From<DateDurationUnit> for icu_calendar::types::DateDurationUnit {
+impl From<DateDurationUnit> for icu_calendar::options::DateDurationUnit {
     fn from(other: DateDurationUnit) -> Self {
         match other {
             DateDurationUnit::Years => Self::Years,

diff --git a/components/calendar/src/calendar_arithmetic.rs b/components/calendar/src/calendar_arithmetic.rs
index 2f68a5d..64bc1b8 100644
--- a/components/calendar/src/calendar_arithmetic.rs
+++ b/components/calendar/src/calendar_arithmetic.rs

@@ -4,12 +4,12 @@
 
 use calendrical_calculations::rata_die::RataDie;
 
-use crate::duration::{DateDuration, DateDurationUnit};
+use crate::duration::DateDuration;
 use crate::error::{
     range_check, DateAddError, DateFromFieldsError, EcmaReferenceYearError, LunisolarDateError,
     MonthCodeParseError, MonthError, UnknownEraError,
 };
-use crate::options::{DateAddOptions, DateDifferenceOptions};
+use crate::options::{DateAddOptions, DateDifferenceOptions, DateDurationUnit};
 use crate::options::{DateFromFieldsOptions, MissingFieldsStrategy, Overflow};
 use crate::types::{DateFields, Month};
 use crate::{types, Calendar, DateError, RangeError};

diff --git a/components/calendar/src/duration.rs b/components/calendar/src/duration.rs
index 9e00f80..b9c4082 100644
--- a/components/calendar/src/duration.rs
+++ b/components/calendar/src/duration.rs

@@ -20,7 +20,7 @@
 /// ```rust
 /// use icu::calendar::options::DateDifferenceOptions;
 /// use icu::calendar::types::DateDuration;
-/// use icu::calendar::types::DateDurationUnit;
+/// use icu::calendar::options::DateDurationUnit;
 /// use icu::calendar::types::Weekday;
 /// use icu::calendar::Date;
 ///
@@ -135,30 +135,6 @@
     pub days: u64,
 }
 
-/// A "duration unit" used to specify the minimum or maximum duration of time to
-/// care about
-///
-/// <div class="stab unstable">
-/// 🚧 This code is considered unstable; it may change at any time, in breaking or non-breaking ways,
-/// including in SemVer minor releases. Do not use this type unless you are prepared for things to occasionally break.
-///
-/// Graduation tracking issue: [issue #3964](https://github.com/unicode-org/icu4x/issues/3964).
-/// </div>
-///
-/// ✨ *Enabled with the `unstable` Cargo feature.*
-#[derive(Copy, Clone, Eq, PartialEq, Debug)]
-#[allow(clippy::exhaustive_enums)] // this type should be stable
-pub enum DateDurationUnit {
-    /// Duration in years
-    Years,
-    /// Duration in months
-    Months,
-    /// Duration in weeks
-    Weeks,
-    /// Duration in days
-    Days,
-}
-
 impl DateDuration {
     /// Parses an ISO 8601 date-only duration string into a [`DateDuration`].
     ///

diff --git a/components/calendar/src/error.rs b/components/calendar/src/error.rs
index ba8019b..708720c 100644
--- a/components/calendar/src/error.rs
+++ b/components/calendar/src/error.rs

@@ -570,7 +570,7 @@
     /// use icu::calendar::error::MismatchedCalendarError;
     /// use icu::calendar::Date;
     /// use icu::calendar::options::DateDifferenceOptions;
-    /// use icu::calendar::types::DateDurationUnit;
+    /// use icu::calendar::options::DateDurationUnit;
     ///
     /// let d1 = Date::try_new_gregorian(2000, 1, 1).unwrap().to_any();
     /// let d2 = Date::try_new_persian(1562, 1, 1).unwrap().to_any();

diff --git a/components/calendar/src/options.rs b/components/calendar/src/options.rs
index 55fa010..6c27671 100644
--- a/components/calendar/src/options.rs
+++ b/components/calendar/src/options.rs

@@ -6,11 +6,13 @@
 
 #[cfg(feature = "unstable")]
 pub use unstable::{
-    DateAddOptions, DateDifferenceOptions, DateFromFieldsOptions, MissingFieldsStrategy, Overflow,
+    DateAddOptions, DateDifferenceOptions, DateDurationUnit, DateFromFieldsOptions,
+    MissingFieldsStrategy, Overflow,
 };
 #[cfg(not(feature = "unstable"))]
 pub(crate) use unstable::{
-    DateAddOptions, DateDifferenceOptions, DateFromFieldsOptions, MissingFieldsStrategy, Overflow,
+    DateAddOptions, DateDifferenceOptions, DateDurationUnit, DateFromFieldsOptions,
+    MissingFieldsStrategy, Overflow,
 };
 
 mod unstable {
@@ -177,12 +179,15 @@
         /// associative or commutative in subsequent arithmetic operations, and it might require
         /// [`Overflow::Constrain`] in addition.
         ///
+        /// The resultant duration will not have any `weeks` value unless [`DateDurationUnit::Weeks`]
+        /// is explicitly specified as `largest_unit`.
+        ///
         /// # Examples
         ///
         /// ```
         /// use icu::calendar::options::DateDifferenceOptions;
         /// use icu::calendar::types::DateDuration;
-        /// use icu::calendar::types::DateDurationUnit;
+        /// use icu::calendar::options::DateDurationUnit;
         /// use icu::calendar::Date;
         ///
         /// let d1 = Date::try_new_iso(2025, 3, 31).unwrap();
@@ -206,6 +211,7 @@
         /// assert_eq!(
         ///     d1.try_until_with_options(&d2, options_weeks).unwrap(),
         ///     DateDuration {
+        ///         // This is the only time there is a `weeks` value.
         ///         weeks: 58,
         ///         days: 4,
         ///         ..Default::default()
@@ -236,10 +242,10 @@
         /// );
         /// ```
         ///
-        /// [`Months`]: crate::types::DateDurationUnit::Months
-        /// [`Years`]: crate::types::DateDurationUnit::Years
+        /// [`Months`]: crate::options::DateDurationUnit::Months
+        /// [`Years`]: crate::options::DateDurationUnit::Years
         /// [`DateDuration`]: crate::types::DateDuration
-        pub largest_unit: Option<crate::duration::DateDurationUnit>,
+        pub largest_unit: Option<DateDurationUnit>,
     }
 
     /// Whether to constrain or reject out-of-bounds values when constructing a Date.
@@ -410,6 +416,30 @@
         /// the identity of an ordinal month changes from year to year.
         Ecma,
     }
+
+    /// A "duration unit" used to specify the minimum or maximum duration of time to
+    /// care about.
+    ///
+    /// <div class="stab unstable">
+    /// 🚧 This code is considered unstable; it may change at any time, in breaking or non-breaking ways,
+    /// including in SemVer minor releases. Do not use this type unless you are prepared for things to occasionally break.
+    ///
+    /// Graduation tracking issue: [issue #3964](https://github.com/unicode-org/icu4x/issues/3964).
+    /// </div>
+    ///
+    /// ✨ *Enabled with the `unstable` Cargo feature.*
+    #[derive(Copy, Clone, Eq, PartialEq, Debug)]
+    #[allow(clippy::exhaustive_enums)] // this type should be stable
+    pub enum DateDurationUnit {
+        /// Duration in years
+        Years,
+        /// Duration in months
+        Months,
+        /// Duration in weeks
+        Weeks,
+        /// Duration in days
+        Days,
+    }
 }
 #[cfg(test)]
 mod tests {

diff --git a/components/calendar/src/tests/arithmetic.rs b/components/calendar/src/tests/arithmetic.rs
index 15c3535..de3707d 100644
--- a/components/calendar/src/tests/arithmetic.rs
+++ b/components/calendar/src/tests/arithmetic.rs

@@ -2,8 +2,8 @@
 // called LICENSE at the top level of the ICU4X source tree
 // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
 
-use crate::options::{DateAddOptions, DateDifferenceOptions, Overflow};
-use crate::types::{DateDuration, DateDurationUnit, Month};
+use crate::options::{DateAddOptions, DateDifferenceOptions, DateDurationUnit, Overflow};
+use crate::types::{DateDuration, Month};
 use crate::{AsCalendar, Calendar, Date};
 use core::fmt;
 

diff --git a/components/calendar/src/tests/date_arithmetic_snapshot.rs b/components/calendar/src/tests/date_arithmetic_snapshot.rs
index 80d83b6..5cbbba1 100644
--- a/components/calendar/src/tests/date_arithmetic_snapshot.rs
+++ b/components/calendar/src/tests/date_arithmetic_snapshot.rs

@@ -2,8 +2,8 @@
 // called LICENSE at the top level of the ICU4X source tree
 // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
 
-use crate::options::{DateAddOptions, DateDifferenceOptions};
-use crate::types::{DateDuration, DateDurationUnit, RataDie};
+use crate::options::{DateAddOptions, DateDifferenceOptions, DateDurationUnit};
+use crate::types::{DateDuration, RataDie};
 use crate::Date;
 use insta::assert_snapshot;
 use std::fmt::Write;

diff --git a/components/calendar/src/tests/extrema.rs b/components/calendar/src/tests/extrema.rs
index 87be22e..173fdd2 100644
--- a/components/calendar/src/tests/extrema.rs
+++ b/components/calendar/src/tests/extrema.rs

@@ -6,8 +6,10 @@
 use crate::duration::DateDuration;
 use crate::error::DateAddError;
 use crate::error::DateFromFieldsError;
-use crate::options::{DateAddOptions, DateDifferenceOptions, DateFromFieldsOptions, Overflow};
-use crate::types::{DateDurationUnit, DateFields, Month};
+use crate::options::{
+    DateAddOptions, DateDifferenceOptions, DateDurationUnit, DateFromFieldsOptions, Overflow,
+};
+use crate::types::{DateFields, Month};
 use crate::Date;
 use calendrical_calculations::gregorian::fixed_from_gregorian;
 use calendrical_calculations::rata_die::RataDie;

diff --git a/components/calendar/src/types.rs b/components/calendar/src/types.rs
index efe6afe..76d8267 100644
--- a/components/calendar/src/types.rs
+++ b/components/calendar/src/types.rs

@@ -12,7 +12,7 @@
 
 // Export the duration types from here
 #[cfg(feature = "unstable")]
-pub use crate::duration::{DateDuration, DateDurationUnit};
+pub use crate::duration::DateDuration;
 use crate::{calendar_arithmetic::ArithmeticDate, error::MonthCodeParseError};
 
 #[cfg(feature = "unstable")]

diff --git a/components/calendar/tests/arithmetic.rs b/components/calendar/tests/arithmetic.rs
index c786bc8..b75fcba 100644
--- a/components/calendar/tests/arithmetic.rs
+++ b/components/calendar/tests/arithmetic.rs

@@ -6,8 +6,8 @@
 
 use icu_calendar::{
     cal::Hebrew,
-    options::{DateAddOptions, DateDifferenceOptions, Overflow},
-    types::{DateDuration, DateDurationUnit, Month},
+    options::{DateAddOptions, DateDifferenceOptions, DateDurationUnit, Overflow},
+    types::{DateDuration, Month},
     AsCalendar, Calendar, Date, Iso,
 };
 

diff --git a/ffi/capi/bindings/cpp/icu4x/DateDurationUnit.d.hpp b/ffi/capi/bindings/cpp/icu4x/DateDurationUnit.d.hpp
index 86e183c..7c5b55a 100644
--- a/ffi/capi/bindings/cpp/icu4x/DateDurationUnit.d.hpp
+++ b/ffi/capi/bindings/cpp/icu4x/DateDurationUnit.d.hpp

@@ -27,7 +27,7 @@
 
 namespace icu4x {
 /**
- * See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/types/enum.DateDurationUnit.html) for more information.
+ * See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/options/enum.DateDurationUnit.html) for more information.
  */
 class DateDurationUnit {
 public:

diff --git a/ffi/capi/src/date.rs b/ffi/capi/src/date.rs
index a032624..0db2faa 100644
--- a/ffi/capi/src/date.rs
+++ b/ffi/capi/src/date.rs

@@ -34,8 +34,8 @@
         Sunday,
     }
 
-    #[diplomat::enum_convert(icu_calendar::types::DateDurationUnit, needs_wildcard)]
-    #[diplomat::rust_link(icu::calendar::types::DateDurationUnit, Enum)]
+    #[diplomat::enum_convert(icu_calendar::options::DateDurationUnit, needs_wildcard)]
+    #[diplomat::rust_link(icu::calendar::options::DateDurationUnit, Enum)]
     #[cfg(feature = "unstable")]
     #[non_exhaustive]
     pub enum DateDurationUnit {

diff --git a/ffi/dart/lib/src/bindings/DateDurationUnit.g.dart b/ffi/dart/lib/src/bindings/DateDurationUnit.g.dart
index 3c4c488..68dedbd 100644
--- a/ffi/dart/lib/src/bindings/DateDurationUnit.g.dart
+++ b/ffi/dart/lib/src/bindings/DateDurationUnit.g.dart

@@ -3,7 +3,7 @@
 
 part of 'lib.g.dart';
 
-/// See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/types/enum.DateDurationUnit.html) for more information.
+/// See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/options/enum.DateDurationUnit.html) for more information.
 enum DateDurationUnit {
   // ignore: public_member_api_docs
   years,

diff --git a/ffi/mvn/src/main/kotlin/src/main/kotlin/org/unicode/icu4x/DateDurationUnit.kt b/ffi/mvn/src/main/kotlin/src/main/kotlin/org/unicode/icu4x/DateDurationUnit.kt
index 5b994a1..eae3303 100644
--- a/ffi/mvn/src/main/kotlin/src/main/kotlin/org/unicode/icu4x/DateDurationUnit.kt
+++ b/ffi/mvn/src/main/kotlin/src/main/kotlin/org/unicode/icu4x/DateDurationUnit.kt

@@ -8,7 +8,7 @@
 
 internal interface DateDurationUnitLib: Library {
 }
-/** See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/types/enum.DateDurationUnit.html) for more information.
+/** See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/options/enum.DateDurationUnit.html) for more information.
 */
 enum class DateDurationUnit {
     Years,

diff --git a/ffi/npm/lib/DateDurationUnit.d.ts b/ffi/npm/lib/DateDurationUnit.d.ts
index 1d23fe3..430b8f7 100644
--- a/ffi/npm/lib/DateDurationUnit.d.ts
+++ b/ffi/npm/lib/DateDurationUnit.d.ts

@@ -4,7 +4,7 @@
 
 
 /**
- * See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/types/enum.DateDurationUnit.html) for more information.
+ * See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/options/enum.DateDurationUnit.html) for more information.
  */
 export class DateDurationUnit {
 

diff --git a/ffi/npm/lib/DateDurationUnit.mjs b/ffi/npm/lib/DateDurationUnit.mjs
index 789b38a..f284f09 100644
--- a/ffi/npm/lib/DateDurationUnit.mjs
+++ b/ffi/npm/lib/DateDurationUnit.mjs

@@ -5,7 +5,7 @@
 
 
 /**
- * See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/types/enum.DateDurationUnit.html) for more information.
+ * See the [Rust documentation for `DateDurationUnit`](https://docs.rs/icu/2.1.1/icu/calendar/options/enum.DateDurationUnit.html) for more information.
  */
 export class DateDurationUnit {
     #value = undefined;