@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/utils/layoutViewport.ts

@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layoutViewport.ts
+ * @input A window: its innerHeight and innerWidth, its visual viewport's
+ *   width and scale, and its document's root box
+ * @output layoutViewportHeight, the layout viewport's height in layout px
+ *   less a classic horizontal scrollbar, and __resetLayoutViewportForTest
+ * @position Internal shared measurement, not re-exported from the utils
+ *   entry. The keyboard module, BottomSheet's keyboard obstruction and any
+ *   layout that sizes against the layout viewport read it.
+ */
+
+/**
+ * The layout viewport's height, CSS px, in the units of element rects.
+ *
+ * `innerHeight` is the layout viewport's height in most engines. WebKit
+ * reports `innerHeight` and `innerWidth` in the pinch-zoomed visual
+ * viewport's px instead. At a 1.33 zoom of a 402 × 714 layout viewport,
+ * Safari on iOS 26.2 reports 536 and 302. Element rects and the visual
+ * viewport's height times its scale stay in layout px. So, read as is, a zoom
+ * shrinks the layout viewport by the zoom, and the function scales the height
+ * back.
+ */
+export function layoutViewportHeight(win: Window): number {
+  const viewport = win.visualViewport;
+  const width = viewport?.width ?? 0;
+  if (viewport == null || !(width > 0)) {
+    return win.innerHeight - horizontalScrollbarHeight(win);
+  }
+  const scale = viewport.scale;
+  // Which units `innerWidth` is in tells the two apart without naming an
+  // engine. It is the visual viewport's width where the zoom applies, and
+  // that width times the scale where it does not. `innerWidth` is a whole
+  // number of px against a fractional width, so it never equals either, and
+  // the nearest wins with no tolerance constant. At a scale of 1 the two
+  // widths are equal, so the function takes `innerHeight` as it is. A classic
+  // scrollbar, which `innerWidth` counts, then changes nothing.
+  const fromVisual = Math.abs(win.innerWidth - width);
+  const fromLayout = Math.abs(win.innerWidth - width * scale);
+  const height =
+    fromVisual < fromLayout ? win.innerHeight * scale : win.innerHeight;
+  return height - horizontalScrollbarHeight(win);
+}
+
+/**
+ * The document's classic horizontal scrollbar, CSS px. It is in
+ * `innerHeight` but not in the visual viewport's height. On a desktop page
+ * wider than its window, Chromium's `innerHeight` is 800 for a 785 px visual
+ * viewport. It is the part of `innerHeight` the root's client height leaves
+ * out, up to the thickness of a scrollbar that takes room. Where scrollbars
+ * overlay the content, as on every phone, that thickness is 0. So the room a
+ * hidden toolbar adds to `innerHeight` is never taken for a scrollbar. Chrome
+ * on Android sizes the root to the viewport with its toolbar shown.
+ */
+function horizontalScrollbarHeight(win: Window): number {
+  const root = win.document.documentElement;
+  const gap = win.innerHeight - root.clientHeight;
+  if (!(gap > 0) || root.scrollWidth <= root.clientWidth) {
+    return 0;
+  }
+  return Math.min(gap, scrollbarThickness(win.document));
+}
+
+// The scrollbar thickness each document measured, and the device pixel ratio
+// it measured it at. A browser zoom changes the ratio, and with it how many
+// CSS px a classic scrollbar takes. Measuring writes a probe to the document
+// and forces a layout, so it runs once per document and zoom. Every later
+// measurement stays one layout read.
+let thicknesses = new WeakMap<
+  Document,
+  {devicePixelRatio: number; thickness: number}
+>();
+
+/** How much room a scrollbar takes from a scrolling box: 0 where overlaid. */
+function scrollbarThickness(doc: Document): number {
+  const devicePixelRatio = doc.defaultView?.devicePixelRatio ?? 1;
+  const known = thicknesses.get(doc);
+  if (known != null && known.devicePixelRatio === devicePixelRatio) {
+    return known.thickness;
+  }
+  const thickness = measureScrollbarThickness(doc);
+  thicknesses.set(doc, {devicePixelRatio, thickness});
+  return thickness;
+}
+
+function measureScrollbarThickness(doc: Document): number {
+  const probe = doc.createElement('div');
+  probe.style.position = 'absolute';
+  probe.style.top = '-200px';
+  probe.style.width = '100px';
+  probe.style.height = '100px';
+  probe.style.overflow = 'scroll';
+  probe.style.visibility = 'hidden';
+  (doc.body ?? doc.documentElement).append(probe);
+  const thickness = probe.offsetHeight - probe.clientHeight;
+  probe.remove();
+  return thickness;
+}
+
+/** Forgets every measured scrollbar thickness. Tests only. */
+export function __resetLayoutViewportForTest(): void {
+  thicknesses = new WeakMap();
+}

package/src/utils/plainDate.ts

@@ -173,6 +173,38 @@ export function getTimeZoneParts(
   };
 }
 
+/** The wall-clock fields of an instant: in a zone, or in the viewer's. */
+export interface WallClock {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+}
+
+/**
+ * Wall-clock fields for an instant, in the named zone or in the viewer's
+ * zone (`undefined`, `null` or ""). The zone-less branch reads plain `Date`
+ * getters, so the default rendering needs no `Intl` zone data. The explicit
+ * return type keeps both branches on one shape.
+ */
+export function getWallClock(
+  date: Date,
+  timeZone: string | null | undefined,
+): WallClock {
+  return !timeZone
+    ? {
+        year: date.getFullYear(),
+        month: date.getMonth() + 1,
+        day: date.getDate(),
+        hour: date.getHours(),
+        minute: date.getMinutes(),
+        second: date.getSeconds(),
+      }
+    : getTimeZoneParts(date.getTime(), timeZone);
+}
+
 function getTimezoneOffsetMS(timezoneID: string, instant: number): number {
   const parts = getTimeZoneParts(instant, timezoneID);
   return (
@@ -359,14 +391,37 @@ export function plainDateFormatStandaloneMonthYear(
 
 // e.g. "Sun" (locale-dependent) — the weekday on its own, abbreviated.
 //
-// This is CLDR's `abbreviated` width, which `Intl` reaches natively. Note
-// that Calendar's 2-letter header ("Su") is CLDR's *short* width, a
-// different thing that `Intl` cannot express at all — which is why that one
-// needs the generated lookup table beside it and this one does not.
+// This is CLDR's `abbreviated` width. Weekday headers prefer a generated
+// table, because `Intl` has no short width.
 export const DATE_FORMAT_WEEKDAY_ONLY: Intl.DateTimeFormatOptions = {
   weekday: 'short',
 };
 
+/**
+ * The platform's weekday names for a locale, Sunday first, in `Intl`'s
+ * `short` width (CLDR's abbreviated) or its `narrow` width. Returns `null`
+ * when the platform has no data for the locale's language, so a caller uses
+ * its own fallback instead of the host's default locale.
+ */
+export function plainDateWeekdayNames(
+  locale: Locale,
+  width: 'short' | 'narrow' = 'short',
+): string[] | null {
+  const options: Intl.DateTimeFormatOptions = {weekday: width};
+  // A language the platform lacks resolves to the host's default locale.
+  const resolved = dateTimeFormatFor(locale, {
+    ...options,
+    calendar: 'gregory',
+  }).resolvedOptions().locale;
+  if (new Intl.Locale(resolved).language !== new Intl.Locale(locale).language) {
+    return null;
+  }
+  // January 4, 1970 was a Sunday.
+  return Array.from({length: 7}, (_, day) =>
+    plainDateFormat({year: 1970, month: 1, day: 4 + day}, options, locale),
+  );
+}
+
 // e.g. "January" (locale-dependent) — the month on its own, for a control
 // that shows a list of months and carries the year separately.
 export const DATE_FORMAT_MONTH_ONLY: Intl.DateTimeFormatOptions = {
@@ -488,6 +543,27 @@ export function plainDateWeekFieldName(locale: Locale = 'en'): string {
   return 'week';
 }
 
+const dayNumberFormats = new Map<Locale, Intl.NumberFormat>();
+
+/**
+ * A day of the month or a week number in the locale's own digits: `15` in
+ * English, `۱۵` in Persian, `١٥` in Egyptian Arabic. Only the digits follow the
+ * locale. The number stays the Gregorian day or ISO week that it names, so no
+ * other calendar applies, and no grouping separator or unit word is added.
+ * Internal: not re-exported from `utils/index.ts`.
+ */
+export function plainDateFormatDayNumber(
+  value: number,
+  locale: Locale,
+): string {
+  let format = dayNumberFormats.get(locale);
+  if (format == null) {
+    format = new Intl.NumberFormat(locale, {useGrouping: false});
+    dayNumberFormats.set(locale, format);
+  }
+  return format.format(value);
+}
+
 // =============================================================================
 // Shared date-only format vocabulary
 // =============================================================================

package/src/utils/pressFeedback.ts

@@ -2,11 +2,11 @@
 
 /**
  * @file pressFeedback.ts
- * @input The press state machine (pressGesture.ts), the menu-press marker
- *   (hooks/menuPressMarker.ts) and the document's pointer, keyboard, scroll and
+ * @input The press state machine (pressGesture.ts), the menu-press and
+ *   press-group markers and the document's pointer, keyboard, scroll and
  *   visibility events
- * @output PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps and
- *   installPressFeedback
+ * @output PRESSABLE_ATTRIBUTE, PRESSED_ATTRIBUTE, pressableProps,
+ *   pressFadeMs and installPressFeedback
  * @position The DOM half of the touch press model. usePressFeedback installs
  *   it, and the CSS arms live in interactionOverlay.stylex.ts.
  *
@@ -46,6 +46,7 @@ import {isCoarsePointer, watchCoarsePointer} from './coarsePointer';
 import {subscribeInput} from './inputStream';
 import {TOUCH_QUERY} from './touchPresentation';
 import {holdsPressThroughDrag} from '../privateAttributes/pressHoldsDrag.stylex';
+import {isTrackedByGroup} from '../privateAttributes/pressGroupItem.stylex';
 
 /**
  * The marker the controller finds with `closest()`. Every Astryx component
@@ -108,7 +109,8 @@ interface LiveGesture {
    * for a press of the Space key.
    */
   pointerId: number | null;
-  timer: ReturnType<typeof setTimeout> | null;
+  /** Cancels the clock the current phase owes, or the release it waits for. */
+  timer: (() => void) | null;
 }
 
 /**
@@ -152,7 +154,7 @@ const TIMER_MS: Record<NonNullable<PressStep['timer']>, number> = {
  * property its stylesheet reads: the theme's `--_astryx-motion-tempo`. Under
  * Reduce Motion a tempo may shorten the fade, never lengthen it past 200 ms.
  */
-function fadeMs(element: Element): number {
+export function pressFadeMs(element: Element): number {
   const style = getComputedStyle(element);
   const value = style.getPropertyValue('--_astryx-motion-tempo').trim();
   const read = value === '' ? Number.NaN : Number(value);
@@ -164,6 +166,76 @@ function fadeMs(element: Element): number {
   return reduced ? Math.min(scaled, PRESS_FADE_MS) : scaled;
 }
 
+/**
+ * The release animations that still run for `element`'s press. Each is a
+ * finite CSS animation that has not finished. It runs on the element, on its
+ * `::before` or `::after`, or on a descendant whose nearest press owner is
+ * the element, because a component can draw its release on a part inside the
+ * surface. A press owner nested inside plays the release of its own press,
+ * so it never extends this one. The list is empty where the engine has no Web
+ * Animations.
+ */
+function releaseAnimationsOf(element: Element): Animation[] {
+  if (typeof element.getAnimations !== 'function') {
+    return [];
+  }
+  return element.getAnimations({subtree: true}).filter(animation => {
+    // The effect of a CSS animation is a KeyframeEffect. Its target is the
+    // element, also when the animation runs on a pseudo-element.
+    const effect = animation.effect as KeyframeEffect | null;
+    const target = effect?.target ?? null;
+    if (
+      effect == null ||
+      target == null ||
+      !('animationName' in animation) ||
+      (target !== element &&
+        target.closest(`[${PRESSABLE_ATTRIBUTE}]`) !== element)
+    ) {
+      return false;
+    }
+    if (!Number.isFinite(Number(effect.getComputedTiming().endTime))) {
+      return false;
+    }
+    return animation.playState !== 'finished';
+  });
+}
+
+/**
+ * Calls `end` when the release on `element` is over. A busy main thread
+ * delays the first frame of the release animation, and with it the end. So a
+ * clock that starts at the `fading` write can cut the release short. When
+ * `clockMs` runs out, the release waits for each release animation that still
+ * runs or still waits for its first frame. It ends when those finish or are
+ * cancelled, as when the surface is unmounted or restyled. With no release
+ * animation (an instant release, a surface without one, an engine without Web
+ * Animations), the release ends at the clock. Returns a cancel.
+ */
+function endAfterRelease(
+  element: Element,
+  clockMs: number,
+  end: () => void,
+): () => void {
+  let waiting = true;
+  const timer = setTimeout(() => {
+    const running = releaseAnimationsOf(element);
+    if (running.length === 0) {
+      end();
+      return;
+    }
+    void Promise.allSettled(
+      running.map(async animation => animation.finished),
+    ).then(() => {
+      if (waiting) {
+        end();
+      }
+    });
+  }, clockMs);
+  return () => {
+    waiting = false;
+    clearTimeout(timer);
+  };
+}
+
 const TIMER_EVENT = {
   fade: 'fadeEnd',
   flash: 'flashEnd',
@@ -180,7 +252,7 @@ function paintElement(element: HTMLElement, paint: PressPaint): void {
 
 function clearTimer(slot: Slot): void {
   if (slot.live?.timer != null) {
-    clearTimeout(slot.live.timer);
+    slot.live.timer();
     slot.live.timer = null;
   }
 }
@@ -216,25 +288,32 @@ function apply(slot: Slot, step: PressStep): void {
   }
   if (step.timer != null) {
     const kind = step.timer;
-    // A TIMER, never `requestAnimationFrame`: iOS throttles frame callbacks
-    // while a scroll runs, so a frame-based delay would fire late, after the
-    // scroll, and paint a control nobody is pressing any more.
-    live.timer = setTimeout(
-      () => {
-        if (slot.live != null) {
-          slot.live.timer = null;
-        }
-        apply(
-          slot,
-          pressGestureStep(slot.live?.gesture ?? idlePressGesture(), {
-            kind: TIMER_EVENT[kind],
-          }),
-        );
-      },
-      // The release fade follows the theme's tempo (AST-108). The onset delay
-      // and the tap flash do not.
-      kind === 'fade' ? fadeMs(live.element) : TIMER_MS[kind],
-    );
+    const fire = () => {
+      if (slot.live != null) {
+        slot.live.timer = null;
+      }
+      apply(
+        slot,
+        pressGestureStep(slot.live?.gesture ?? idlePressGesture(), {
+          kind: TIMER_EVENT[kind],
+        }),
+      );
+    };
+    if (kind === 'fade') {
+      // The release fade follows the theme's tempo (AST-108). It ends when
+      // its animation ends, however late a busy main thread let it start.
+      live.timer = endAfterRelease(
+        live.element,
+        pressFadeMs(live.element),
+        fire,
+      );
+    } else {
+      // A TIMER, never `requestAnimationFrame`: iOS throttles frame callbacks
+      // while a scroll runs, so a frame-based delay would fire late, after the
+      // scroll, and paint a control nobody is pressing any more.
+      const timer = setTimeout(fire, TIMER_MS[kind]);
+      live.timer = () => clearTimeout(timer);
+    }
   }
 }
 
@@ -325,8 +404,9 @@ function stylesheetDroppedActive(): boolean {
 
 /**
  * The surface a mouse button's or the Space key's press paints, if any: the
- * innermost marked surface, outside a menu. A key's press paints only a
- * focused element that is itself the surface, as `:active` does.
+ * innermost marked surface, outside a menu and off a tracked action. A key's
+ * press paints only a focused element that is itself the surface, as
+ * `:active` does.
  */
 function buttonSurfaceAt(
   target: EventTarget | null,
@@ -336,6 +416,10 @@ function buttonSurfaceAt(
   if (element == null || element.closest(MENU_PRESS_ROOT) != null) {
     return null;
   }
+  // A tracker that follows a mouse paints a mouse press on its own actions.
+  if (pointerId != null && isTrackedByGroup(element, 'mouse')) {
+    return null;
+  }
   if (pointerId == null && element !== target) {
     return null;
   }
@@ -414,7 +498,14 @@ function onPointerDown(event: PointerEvent): void {
   const braking = element != null && scrollerIsBraking(element);
   lastTouchAt = Date.now();
   lastTouchTarget = event.target instanceof Node ? event.target : null;
-  if (element == null || braking) {
+  // A group's tracker that follows this pointer paints its action, so two
+  // writers would erase each other's paint. The touch still counts for the
+  // brake above.
+  if (
+    element == null ||
+    braking ||
+    isTrackedByGroup(element, event.pointerType)
+  ) {
     return;
   }
   takeOver(button, element);
@@ -560,6 +651,11 @@ function activatesOnSpace(target: EventTarget | null): boolean {
   );
 }
 
+/** A tracked action takes no `:active` paint, so a key's press paints here. */
+function isTrackedAction(target: EventTarget | null): boolean {
+  return target instanceof Element && isTrackedByGroup(target);
+}
+
 /**
  * Space went down on a focused button that is itself a pressable surface.
  * Heard in the BUBBLE phase, after the page's own handlers, so a press the
@@ -573,7 +669,7 @@ function onKeyDown(event: KeyboardEvent): void {
     event.isComposing ||
     event.defaultPrevented ||
     !activatesOnSpace(event.target) ||
-    !stylesheetDroppedActive()
+    !(stylesheetDroppedActive() || isTrackedAction(event.target))
   ) {
     return;
   }

package/src/utils/pressGesture.ts

@@ -62,7 +62,9 @@ export const PRESS_FLASH_MS = 100;
  * How long the paint takes to leave after a release: UIKit's deselect
  * crossfade. The one number, shared with the stylesheet: the release
  * animation in interactionOverlay.stylex.ts runs on the same constant, so the
- * timer that removes the attribute and the fade cannot drift apart.
+ * controller's release clock and the fade cannot drift apart. When the clock
+ * runs out, the controller waits for a release animation that still runs,
+ * then removes the attribute.
  */
 export const PRESS_FADE_MS: number = pressConsts.releaseMs;
 
@@ -119,7 +121,7 @@ export type PressEvent =
   | {kind: 'onset'}
   /** {@link PRESS_FLASH_MS} elapsed on a too-quick tap. */
   | {kind: 'flashEnd'}
-  /** {@link PRESS_FADE_MS} elapsed; the paint is gone. */
+  /** The release is over: its animation ended, or its clock ran out with none running. */
   | {kind: 'fadeEnd'};
 
 export interface PressStep {

package/src/utils/selectionLock.ts

@@ -116,6 +116,16 @@ export interface DragSelectionReleaseOptions {
   isCancel?: boolean;
 }
 
+/** A drag's selection hold: call it to release the hold. */
+export interface DragSelectionHold {
+  (options?: DragSelectionReleaseOptions): void;
+  /**
+   * Called after the lift's own handlers ran. A selection they made since
+   * the release stays: the hold then puts it back, not the press's.
+   */
+  keepLiftSelection(): void;
+}
+
 /**
  * Refuse a new selection while a mouse or pen drag that a recognizer claimed
  * runs, until the returned function runs. `kept` is the page's selection
@@ -140,9 +150,13 @@ export function lockDragSelection(
   view: Window | null | undefined,
   kept: ReadonlyArray<AbstractRange>,
   onReleased?: () => void,
-): (options?: DragSelectionReleaseOptions) => void {
+): DragSelectionHold {
   const doc = view?.document ?? null;
-  const roots = shadowRootsOfRanges(kept);
+  let keptRanges = kept;
+  let roots = shadowRootsOfRanges(keptRanges);
+  // The selection when the lift released the hold, until the lift's
+  // handlers ran.
+  let atLift: ReadonlyArray<AbstractRange> | null = null;
   const restore = () => {
     const selection = view?.getSelection();
     // The focused field keeps its own selection (a drag never starts in one).
@@ -150,7 +164,7 @@ export function lockDragSelection(
       return;
     }
     const held = heldRanges(selection, roots);
-    if (kept.length === 0) {
+    if (keptRanges.length === 0) {
       if (held.some(range => !range.collapsed)) {
         selection.removeAllRanges();
       }
@@ -158,10 +172,10 @@ export function lockDragSelection(
     }
     // A render can remove what the kept selection held: then there is
     // nothing to put back.
-    if (sameRanges(held, kept) || !kept.every(isValidRange)) {
+    if (sameRanges(held, keptRanges) || !keptRanges.every(isValidRange)) {
       return;
     }
-    selectRanges(selection, kept);
+    selectRanges(selection, keptRanges);
   };
   restore();
   const set = new Set(elements);
@@ -201,9 +215,10 @@ export function lockDragSelection(
       onReleased?.();
     }
   };
-  return ({isCancel = false}: DragSelectionReleaseOptions = {}) => {
+  const release = (({isCancel = false}: DragSelectionReleaseOptions = {}) => {
     if (stage === 'held') {
       stage = 'lifted';
+      atLift = selectionRangesOf(view);
       for (const element of set) {
         element.removeEventListener('selectstart', refuse);
       }
@@ -218,7 +233,26 @@ export function lockDragSelection(
     } else if (stage === 'lifted' && isCancel) {
       releaseDocument();
     }
+  }) as DragSelectionHold;
+  release.keepLiftSelection = () => {
+    if (stage !== 'lifted' || atLift == null) {
+      return;
+    }
+    const before = atLift;
+    atLift = null;
+    const keepIfChanged = () => {
+      const now = selectionRangesOf(view);
+      if (stage !== 'done' && !sameRanges(now, before)) {
+        keptRanges = now;
+        roots = shadowRootsOfRanges(now);
+      }
+    };
+    keepIfChanged();
+    // A click's state update renders in a microtask, and its layout effect
+    // may select then. That still runs before the press's own mouseup.
+    queueMicrotask(keepIfChanged);
   };
+  return release;
 }
 
 /**

package/src/utils/sharedMutationObserver.ts

@@ -8,7 +8,8 @@
  * @output Exports observeMutations (one shared observer per set of options)
  *   and observeContent, its text-and-children form
  * @position Internal utility; consumed by useTruncation, hitArea, AppShell's
- *   main-overflow observer and ModalAnnounceProvider's presentation watch. The mutation counterpart of sharedResizeObserver:
+ *   main-overflow observer, ModalAnnounceProvider's presentation watch and
+ *   CheckboxList's required group. The mutation counterpart of sharedResizeObserver:
  *   one observer for every element observed with the same options, so a
  *   repeated cell, row or region does not create one observer per instance.
  */

package/src/utils/timeParser.ts

@@ -341,7 +341,8 @@ export function isTimeInRange(
 }
 
 /**
- * Clamps a time to a min/max range.
+ * Clamps a time to a min/max range. Without seconds, a bound that falls
+ * between whole minutes gives the nearest whole minute inside the range.
  */
 export function clampTime(
   time: ISOTimeString,
@@ -357,19 +358,55 @@ export function clampTime(
   if (min && compareTime(time, min) < 0) {
     const parsedMin = parseISOTime(min);
     if (parsedMin) {
-      return formatISOTime(parsedMin, includeSeconds);
+      return formatISOTime(
+        onWholeMinute(parsedMin, 1, includeSeconds, max),
+        includeSeconds,
+      );
     }
   }
   if (max && compareTime(time, max) > 0) {
     const parsedMax = parseISOTime(max);
     if (parsedMax) {
-      return formatISOTime(parsedMax, includeSeconds);
+      return formatISOTime(
+        onWholeMinute(parsedMax, -1, includeSeconds, min),
+        includeSeconds,
+      );
     }
   }
 
   return time;
 }
 
+/**
+ * A bound as a time without seconds reaches it: the next whole minute up from
+ * a minimum, or the whole minute down from a maximum. With no whole minute
+ * before the other bound, the bound stays as it is.
+ */
+function onWholeMinute(
+  bound: ParsedTime,
+  direction: 1 | -1,
+  includeSeconds: boolean,
+  other: ISOTimeString | undefined,
+): ParsedTime {
+  if (includeSeconds || bound.second === 0) {
+    return bound;
+  }
+  const minutes = bound.hour * 60 + bound.minute + (direction === 1 ? 1 : 0);
+  if (minutes > 23 * 60 + 59) {
+    return bound;
+  }
+  const rounded = {
+    hour: Math.floor(minutes / 60),
+    minute: minutes % 60,
+    second: 0,
+  };
+  const order = compareTime(formatISOTime(rounded, true), other);
+  if (other && (direction === 1 ? order > 0 : order < 0)) {
+    return bound;
+  }
+  return rounded;
+}
+
 /**
  * Adjusts a time by adding/subtracting minutes.
  *