@comitor/ui 3.0.0 → 3.1.0

package/dist/components/ui/time-picker.js

@@ -125,6 +125,208 @@ function getPeriodFromKey(key, labels) {
   if (lowerKey === labels.pm.charAt(0).toLowerCase()) return "PM";
   return null;
 }
+const SECONDS_PER_HOUR = 3600;
+const SECONDS_PER_HALF_DAY = 43200;
+const LAST_SECOND_OF_DAY = 86399;
+const LAST_MINUTE_OF_DAY = LAST_SECOND_OF_DAY - 59;
+function toSeconds(time, showSeconds) {
+  return (time.hour ?? 0) * SECONDS_PER_HOUR + (time.minute ?? 0) * 60 + (showSeconds ? time.second ?? 0 : 0);
+}
+function fromSeconds(seconds) {
+  return {
+    hour: Math.floor(seconds / SECONDS_PER_HOUR),
+    minute: Math.floor(seconds % SECONDS_PER_HOUR / 60),
+    second: seconds % 60
+  };
+}
+function parseTimeBound(bound) {
+  const time = parseTimeString(bound);
+  if (!time || time.hour === void 0 || time.minute === void 0) return null;
+  return toSeconds(time, true);
+}
+function getTimeRange(min, max, showSeconds) {
+  const lower = parseTimeBound(min);
+  const upper = parseTimeBound(max);
+  if (lower === null && upper === null) return null;
+  const range = { min: lower ?? 0, max: upper ?? LAST_SECOND_OF_DAY, wraps: false };
+  range.wraps = range.min > range.max;
+  if (!showSeconds) {
+    range.min = Math.min(Math.ceil(range.min / 60) * 60, LAST_MINUTE_OF_DAY);
+    range.max = Math.floor(range.max / 60) * 60;
+    if (!range.wraps && range.min > range.max) range.min = range.max;
+  }
+  return range;
+}
+function findNearestAllowed(seconds, range, from = 0, to = LAST_SECOND_OF_DAY) {
+  const intervals = range.wraps ? [
+    [0, range.max],
+    [range.min, LAST_SECOND_OF_DAY]
+  ] : [[range.min, range.max]];
+  let nearest = null;
+  for (const [start, end] of intervals) {
+    const low = Math.max(start, from);
+    const high = Math.min(end, to);
+    if (low > high) continue;
+    const candidate = clamp(seconds, low, high);
+    if (nearest === null || Math.abs(candidate - seconds) < Math.abs(nearest - seconds)) {
+      nearest = candidate;
+    }
+  }
+  return nearest;
+}
+function getSegmentSpan(time, segment, showSeconds) {
+  if (time.hour === void 0) return null;
+  const hourStart = time.hour * SECONDS_PER_HOUR;
+  if (segment === "period") {
+    const halfDayStart = time.hour < 12 ? 0 : SECONDS_PER_HALF_DAY;
+    return [halfDayStart, halfDayStart + SECONDS_PER_HALF_DAY - 1];
+  }
+  if (segment === "hour") return [hourStart, hourStart + SECONDS_PER_HOUR - 1];
+  if (time.minute === void 0) return null;
+  const minuteStart = hourStart + time.minute * 60;
+  if (segment === "minute" || !showSeconds) return [minuteStart, minuteStart + 59];
+  if (time.second === void 0) return null;
+  return [minuteStart + time.second, minuteStart + time.second];
+}
+function isSegmentAllowed(time, segment, range, showSeconds) {
+  if (!range) return true;
+  const span = getSegmentSpan(time, segment, showSeconds);
+  return !span || findNearestAllowed(span[0], range, span[0], span[1]) !== null;
+}
+function constrainTime(time, range, showSeconds, keep) {
+  if (!range || time.hour === void 0) return time;
+  const seconds = toSeconds(time, showSeconds);
+  const isComplete = time.minute !== void 0 && (!showSeconds || time.second !== void 0);
+  if (isComplete) {
+    if (findNearestAllowed(seconds, range, seconds, seconds) !== null) return time;
+  } else {
+    const hourStart = time.hour * SECONDS_PER_HOUR;
+    if (findNearestAllowed(hourStart, range, hourStart, hourStart + SECONDS_PER_HOUR - 1) !== null) return time;
+  }
+  const span = keep && isComplete ? getSegmentSpan(time, keep, showSeconds) : null;
+  const nearest = (span && findNearestAllowed(seconds, range, span[0], span[1])) ?? findNearestAllowed(seconds, range) ?? seconds;
+  return fromSeconds(nearest);
+}
+function getReferenceTime(range, showSeconds) {
+  const now = /* @__PURE__ */ new Date();
+  const time = { hour: now.getHours(), minute: now.getMinutes(), second: now.getSeconds() };
+  if (!range) return time;
+  const seconds = toSeconds(time, showSeconds);
+  const nearest = findNearestAllowed(seconds, range);
+  return nearest === null || nearest === seconds ? time : fromSeconds(nearest);
+}
+function buildHourTime(timeValue, displayHour, is12Hour, showSeconds, reference) {
+  const currentTime = timeValue ?? {};
+  let hour24 = displayHour;
+  if (is12Hour) {
+    let currentPeriod;
+    if (timeValue?.period !== void 0) {
+      currentPeriod = timeValue.period;
+    } else if (timeValue?.hour !== void 0) {
+      currentPeriod = to12Hour(timeValue.hour).period;
+    } else {
+      currentPeriod = to12Hour(reference.hour).period;
+    }
+    hour24 = to24Hour(displayHour, currentPeriod);
+  }
+  const newTime = { ...currentTime, hour: hour24 };
+  if (timeValue && timeValue.period !== void 0) {
+    newTime.period = timeValue.period;
+  }
+  if (newTime.minute === void 0) {
+    newTime.minute = reference.minute;
+  }
+  if (showSeconds && newTime.second === void 0) {
+    newTime.second = reference.second;
+  }
+  return newTime;
+}
+function buildMinuteTime(timeValue, minute, showSeconds, reference) {
+  const currentTime = timeValue ?? {};
+  const newTime = { ...currentTime, minute };
+  if (newTime.hour === void 0) {
+    newTime.hour = reference.hour;
+  }
+  if (showSeconds && newTime.second === void 0) {
+    newTime.second = reference.second;
+  }
+  return newTime;
+}
+function buildSecondTime(timeValue, second, reference) {
+  const currentTime = timeValue ?? {};
+  const newTime = { ...currentTime, second };
+  if (newTime.hour === void 0) {
+    newTime.hour = reference.hour;
+  }
+  if (newTime.minute === void 0) {
+    newTime.minute = reference.minute;
+  }
+  return newTime;
+}
+function buildPeriodTime(timeValue, period, showSeconds, reference) {
+  const currentTime = timeValue ?? {};
+  const currentHour = currentTime.hour !== void 0 ? currentTime.hour : reference.hour;
+  const currentDisplay = to12Hour(currentHour);
+  const new24Hour = to24Hour(currentDisplay.hour, period);
+  const newTime = { ...currentTime, hour: new24Hour };
+  if (newTime.minute === void 0) {
+    newTime.minute = reference.minute;
+  }
+  if (showSeconds && newTime.second === void 0) {
+    newTime.second = reference.second;
+  }
+  return newTime;
+}
+function getColumnEntry(items) {
+  return items.find((item) => item.selected && !item.disabled) ?? items.find((item) => !item.disabled) ?? items.find((item) => item.selected) ?? items[0];
+}
+function getColumnEntryRefs(items) {
+  const entry = getColumnEntry(items);
+  const refs = items.map((item) => item.ref);
+  return entry ? [entry.ref, ...refs] : refs;
+}
+function isHiddenWithin(element, container) {
+  if (getComputedStyle(element).visibility === "hidden") return true;
+  for (let node = element; node && node !== container; node = node.parentElement) {
+    if (getComputedStyle(node).display === "none") return true;
+  }
+  return false;
+}
+function getTabbableElements(container) {
+  const elements = [];
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, {
+    acceptNode: (node) => {
+      const element = node;
+      const isHiddenInput = element instanceof HTMLInputElement && element.type === "hidden";
+      if (element.disabled || element.hidden || isHiddenInput) {
+        return NodeFilter.FILTER_SKIP;
+      }
+      return element.tabIndex >= 0 ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+    }
+  });
+  while (walker.nextNode()) elements.push(walker.currentNode);
+  return elements.filter((element) => !isHiddenWithin(element, container));
+}
+function getTabTarget(content, column, backward) {
+  const tabbables = getTabbableElements(content);
+  const isOutsideColumn = (element) => !column.contains(element);
+  if (backward) {
+    for (let index = tabbables.length - 1; index >= 0; index--) {
+      const element = tabbables[index];
+      if (element && isOutsideColumn(element) && (column.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_PRECEDING) !== 0) {
+        return element;
+      }
+    }
+    return tabbables[tabbables.length - 1];
+  }
+  return tabbables.find(
+    (element) => isOutsideColumn(element) && (column.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0
+  ) ?? tabbables[0];
+}
+function focusTabbable(element) {
+  element.focus();
+  if (element instanceof HTMLInputElement) element.select();
+}
 const StoreContext = React.createContext(null);
 function useStoreContext(consumerName) {
   const context = React.useContext(StoreContext);
@@ -259,6 +461,7 @@ function TimePicker(props) {
     };
   }, [segmentPlaceholder]);
   const labels = useComitorLabels("timePicker", labelsProp);
+  const timeRange = React.useMemo(() => getTimeRange(min, max, showSeconds), [min, max, showSeconds]);
   const rootContext = React.useMemo(
     () => ({
       id: rootId,
@@ -282,7 +485,8 @@ function TimePicker(props) {
       segmentPlaceholder: normalizedPlaceholder,
       labels,
       min,
-      max
+      max,
+      timeRange
     }),
     [
       rootId,
@@ -303,7 +507,8 @@ function TimePicker(props) {
       normalizedPlaceholder,
       labels,
       min,
-      max
+      max,
+      timeRange
     ]
   );
   const RootPrimitive = asChild ? Slot : "div";
@@ -507,6 +712,33 @@ function TimePickerInputGroup(props) {
     }
   ) }) });
 }
+function getSegmentText(timeValue, segment, is12Hour, segmentPlaceholder) {
+  if (!timeValue) {
+    if (!segment) return "";
+    return segmentPlaceholder[segment];
+  }
+  switch (segment) {
+    case "hour": {
+      if (timeValue.hour === void 0) return segmentPlaceholder.hour;
+      if (is12Hour) {
+        return to12Hour(timeValue.hour).hour.toString().padStart(2, "0");
+      }
+      return timeValue.hour.toString().padStart(2, "0");
+    }
+    case "minute":
+      if (timeValue.minute === void 0) return segmentPlaceholder.minute;
+      return timeValue.minute.toString().padStart(2, "0");
+    case "second":
+      if (timeValue.second === void 0) return segmentPlaceholder.second;
+      return timeValue.second.toString().padStart(2, "0");
+    case "period": {
+      if (!timeValue || timeValue.hour === void 0) return segmentPlaceholder.period;
+      return to12Hour(timeValue.hour).period;
+    }
+    default:
+      return "";
+  }
+}
 function TimePickerInput(props) {
   const {
     segment,
@@ -522,7 +754,7 @@ function TimePickerInput(props) {
     ref,
     ...inputProps
   } = props;
-  const { is12Hour, showSeconds, disabled, readOnly, invalid, segmentPlaceholder, labels, openOnFocus } = useTimePickerContext(INPUT_NAME);
+  const { is12Hour, showSeconds, disabled, readOnly, invalid, segmentPlaceholder, labels, openOnFocus, timeRange } = useTimePickerContext(INPUT_NAME);
   const store = useStoreContext(INPUT_NAME);
   const inputGroupContext = useTimePickerInputGroupContext(INPUT_NAME);
   const isDisabled = disabledProp || disabled;
@@ -537,33 +769,10 @@ function TimePickerInput(props) {
       return () => inputGroupContext.onInputUnregister(segment);
     }
   }, [inputGroupContext, segment]);
-  const getSegmentValue = React.useCallback(() => {
-    if (!timeValue) {
-      if (!segment) return "";
-      return segmentPlaceholder[segment];
-    }
-    switch (segment) {
-      case "hour": {
-        if (timeValue.hour === void 0) return segmentPlaceholder.hour;
-        if (is12Hour) {
-          return to12Hour(timeValue.hour).hour.toString().padStart(2, "0");
-        }
-        return timeValue.hour.toString().padStart(2, "0");
-      }
-      case "minute":
-        if (timeValue.minute === void 0) return segmentPlaceholder.minute;
-        return timeValue.minute.toString().padStart(2, "0");
-      case "second":
-        if (timeValue.second === void 0) return segmentPlaceholder.second;
-        return timeValue.second.toString().padStart(2, "0");
-      case "period": {
-        if (!timeValue || timeValue.hour === void 0) return segmentPlaceholder.period;
-        return to12Hour(timeValue.hour).period;
-      }
-      default:
-        return "";
-    }
-  }, [timeValue, segment, is12Hour, segmentPlaceholder]);
+  const getSegmentValue = React.useCallback(
+    () => getSegmentText(timeValue, segment, is12Hour, segmentPlaceholder),
+    [timeValue, segment, is12Hour, segmentPlaceholder]
+  );
   const [editValue, setEditValue] = React.useState(getSegmentValue());
   const [isEditing, setIsEditing] = React.useState(false);
   const [pendingDigit, setPendingDigit] = React.useState(null);
@@ -592,8 +801,7 @@ function TimePickerInput(props) {
               } else if (timeValue?.hour !== void 0) {
                 currentPeriod = to12Hour(timeValue.hour).period;
               } else {
-                const now = /* @__PURE__ */ new Date();
-                currentPeriod = to12Hour(now.getHours()).period;
+                currentPeriod = to12Hour(getReferenceTime(timeRange, showSeconds).hour).period;
               }
               const hour24 = to24Hour(clampedHour, currentPeriod);
               newTime.hour = hour24;
@@ -632,9 +840,17 @@ function TimePickerInput(props) {
         }
       }
       const newValue = formatTimeValue(newTime, showSeconds);
-      store.setState("value", newValue);
+      if (newValue === store.getState().value) return;
+      const committedTime = constrainTime(newTime, timeRange, showSeconds, segment);
+      if (committedTime === newTime) {
+        store.setState("value", newValue);
+        return;
+      }
+      store.setState("value", formatTimeValue(committedTime, showSeconds));
+      setEditValue(getSegmentText(committedTime, segment, is12Hour, segmentPlaceholder));
+      setPendingDigit(null);
     },
-    [timeValue, segment, is12Hour, showSeconds, store, segmentPlaceholder]
+    [timeValue, segment, is12Hour, showSeconds, store, segmentPlaceholder, timeRange]
   );
   const onBlur = React.useCallback(
     (event) => {
@@ -658,23 +874,23 @@ function TimePickerInput(props) {
         queueMicrotask(() => {
           const currentTimeValue = parseTimeString(store.getState().value);
           if (currentTimeValue) {
-            const now = /* @__PURE__ */ new Date();
+            const now = getReferenceTime(timeRange, showSeconds);
             const newTime = { ...currentTimeValue };
             let needsUpdate = false;
             if (newTime.hour === void 0) {
-              newTime.hour = now.getHours();
+              newTime.hour = now.hour;
               needsUpdate = true;
             }
             if (newTime.minute === void 0) {
-              newTime.minute = now.getMinutes();
+              newTime.minute = now.minute;
               needsUpdate = true;
             }
             if (showSeconds && newTime.second === void 0) {
-              newTime.second = now.getSeconds();
+              newTime.second = now.second;
               needsUpdate = true;
             }
             if (needsUpdate) {
-              const newValue = formatTimeValue(newTime, showSeconds);
+              const newValue = formatTimeValue(constrainTime(newTime, timeRange, showSeconds, segment), showSeconds);
               store.setState("value", newValue);
             }
           }
@@ -683,7 +899,17 @@ function TimePickerInput(props) {
       setEditValue(getSegmentValue());
       setPendingDigit(null);
     },
-    [onBlurProp, editValue, updateTimeValue, getSegmentValue, segment, segmentPlaceholder, showSeconds, store]
+    [
+      onBlurProp,
+      editValue,
+      updateTimeValue,
+      getSegmentValue,
+      segment,
+      segmentPlaceholder,
+      showSeconds,
+      store,
+      timeRange
+    ]
   );
   const onChange = React.useCallback(
     (event) => {
@@ -1104,11 +1330,14 @@ function TimePickerContent(props) {
     className,
     onOpenAutoFocus: onOpenAutoFocusProp,
     onInteractOutside: onInteractOutsideProp,
+    ref,
     ...contentProps
   } = props;
   const store = useStoreContext(CONTENT_NAME);
   const { openOnFocus, inputGroupRef } = useTimePickerContext(CONTENT_NAME);
   const columnsRef = React.useRef(/* @__PURE__ */ new Map());
+  const contentRef = React.useRef(null);
+  const composedRef = useComposedRefs(ref, contentRef);
   const onColumnRegister = React.useCallback((column) => {
     columnsRef.current.set(column.id, column);
   }, []);
@@ -1116,9 +1345,9 @@ function TimePickerContent(props) {
     columnsRef.current.delete(id);
   }, []);
   const getColumns = React.useCallback(() => {
-    const columns = Array.from(columnsRef.current.entries()).map(([id, { ref, getSelectedItemRef, getItems }]) => ({
+    const columns = Array.from(columnsRef.current.entries()).map(([id, { ref: ref2, getSelectedItemRef, getItems }]) => ({
       id,
-      ref,
+      ref: ref2,
       getSelectedItemRef,
       getItems
     })).filter((c) => c.ref.current !== null);
@@ -1128,7 +1357,8 @@ function TimePickerContent(props) {
     () => ({
       getColumns,
       onColumnRegister,
-      onColumnUnregister
+      onColumnUnregister,
+      contentRef
     }),
     [getColumns, onColumnRegister, onColumnUnregister]
   );
@@ -1145,10 +1375,7 @@ function TimePickerContent(props) {
       const columns = getColumns();
       const firstColumn = columns[0];
       if (!firstColumn) return;
-      const items = firstColumn.getItems();
-      const selectedItem = items.find((item) => item.selected);
-      const candidateRefs = selectedItem ? [selectedItem.ref, ...items.map((item) => item.ref)] : items.map((item) => item.ref);
-      focusFirst(candidateRefs, false);
+      focusFirst(getColumnEntryRefs(firstColumn.getItems()), false);
     },
     [onOpenAutoFocusProp, getColumns, store]
   );
@@ -1175,6 +1402,7 @@ function TimePickerContent(props) {
       align,
       sideOffset,
       ...contentProps,
+      ref: composedRef,
       className: cn("flex w-auto max-w-(--radix-popover-trigger-width) p-0", className),
       onOpenAutoFocus,
       onInteractOutside
@@ -1197,8 +1425,8 @@ function TimePickerColumn(props) {
   const itemsRef = React.useRef(/* @__PURE__ */ new Map());
   const groupContext = useTimePickerGroupContext(COLUMN_NAME);
   const onItemRegister = React.useCallback(
-    (value, ref2, selected) => {
-      itemsRef.current.set(value, { ref: ref2, selected });
+    (value, ref2, selected, disabled) => {
+      itemsRef.current.set(value, { ref: ref2, selected, disabled });
     },
     []
   );
@@ -1206,10 +1434,11 @@ function TimePickerColumn(props) {
     itemsRef.current.delete(value);
   }, []);
   const getItems = React.useCallback(() => {
-    const items = Array.from(itemsRef.current.entries()).map(([value, { ref: ref2, selected }]) => ({
+    const items = Array.from(itemsRef.current.entries()).map(([value, { ref: ref2, selected, disabled }]) => ({
       value,
       ref: ref2,
-      selected
+      selected,
+      disabled
     })).filter((item) => item.ref.current);
     return sortNodes(items);
   }, []);
@@ -1247,15 +1476,25 @@ function TimePickerColumn(props) {
   ) });
 }
 function TimePickerColumnItem(props) {
-  const { value, selected = false, format = "numeric", className, children, ref, ...itemProps } = props;
+  const {
+    value,
+    selected = false,
+    // ⚠ Khác thượng nguồn (3.1.0): mục bị khoá theo `min`/`max` — xem cuối chú thích ở thẻ `<button>`.
+    disabled = false,
+    format = "numeric",
+    className,
+    children,
+    ref,
+    ...itemProps
+  } = props;
   const itemRef = React.useRef(null);
   const composedRef = useComposedRefs(ref, itemRef);
   const columnContext = useTimePickerColumnContext(COLUMN_ITEM_NAME);
   const groupContext = useTimePickerGroupContext(COLUMN_ITEM_NAME);
   useIsomorphicLayoutEffect(() => {
-    columnContext.onItemRegister(value, itemRef, selected);
+    columnContext.onItemRegister(value, itemRef, selected, disabled);
     return () => columnContext.onItemUnregister(value);
-  }, [columnContext, value, selected]);
+  }, [columnContext, value, selected, disabled]);
   useIsomorphicLayoutEffect(() => {
     if (selected && itemRef.current) {
       itemRef.current.scrollIntoView({ block: "nearest" });
@@ -1263,11 +1502,15 @@ function TimePickerColumnItem(props) {
   }, [selected]);
   const onClick = React.useCallback(
     (event) => {
+      if (disabled) {
+        event.preventDefault();
+        return;
+      }
       itemProps.onClick?.(event);
       if (event.defaultPrevented) return;
       itemRef.current?.focus();
     },
-    [itemProps.onClick]
+    [itemProps.onClick, disabled]
   );
   const onKeyDown = React.useCallback(
     (event) => {
@@ -1282,30 +1525,37 @@ function TimePickerColumnItem(props) {
           return 0;
         });
         const currentIndex = items.findIndex((item) => item.value === value);
-        let nextIndex;
-        if (event.key === "ArrowUp") {
-          nextIndex = currentIndex > 0 ? currentIndex - 1 : items.length - 1;
-        } else {
-          nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : 0;
+        const step = event.key === "ArrowUp" ? -1 : 1;
+        const start = currentIndex === -1 ? step > 0 ? -1 : items.length : currentIndex;
+        let nextItem;
+        for (let offset = 1; offset <= items.length; offset++) {
+          const candidate = items[((start + step * offset) % items.length + items.length) % items.length];
+          if (candidate && !candidate.disabled) {
+            nextItem = candidate;
+            break;
+          }
         }
-        const nextItem = items[nextIndex];
         nextItem?.ref.current?.focus();
         nextItem?.ref.current?.click();
-      } else if ((event.key === "Tab" || event.key === "ArrowLeft" || event.key === "ArrowRight") && groupContext) {
+      } else if (event.key === "Tab" && groupContext) {
+        const content = groupContext.contentRef.current;
+        const column = groupContext.getColumns().find((c) => c.ref.current?.contains(itemRef.current) ?? false)?.ref.current;
+        if (!content || !column) return;
+        event.preventDefault();
+        const target = getTabTarget(content, column, event.shiftKey);
+        if (target) queueMicrotask(() => focusTabbable(target));
+      } else if ((event.key === "ArrowLeft" || event.key === "ArrowRight") && groupContext) {
         event.preventDefault();
         queueMicrotask(() => {
           const columns = groupContext.getColumns();
           if (columns.length === 0) return;
           const currentColumnIndex = columns.findIndex((c) => c.ref.current?.contains(itemRef.current) ?? false);
           if (currentColumnIndex === -1) return;
-          const goToPrevious = event.key === "ArrowLeft" || event.key === "Tab" && event.shiftKey;
+          const goToPrevious = event.key === "ArrowLeft";
           const nextColumnIndex = goToPrevious ? currentColumnIndex > 0 ? currentColumnIndex - 1 : columns.length - 1 : currentColumnIndex < columns.length - 1 ? currentColumnIndex + 1 : 0;
           const nextColumn = columns[nextColumnIndex];
           if (nextColumn?.ref.current) {
-            const items = nextColumn.getItems();
-            const selectedItem = items.find((item) => item.selected);
-            const candidateRefs = selectedItem ? [selectedItem.ref, ...items.map((item) => item.ref)] : items.map((item) => item.ref);
-            focusFirst(candidateRefs, false);
+            focusFirst(getColumnEntryRefs(nextColumn.getItems()), false);
           }
         });
       }
@@ -1319,9 +1569,11 @@ function TimePickerColumnItem(props) {
       type: "button",
       role: "option",
       "aria-selected": selected,
+      "aria-disabled": disabled || void 0,
       ...itemProps,
       ref: composedRef,
       "data-selected": selected ? "" : void 0,
+      "data-disabled": disabled ? "" : void 0,
       className: cn(
         /*
          * ⚠ Khác thượng nguồn: focus đi theo khuôn `Checkbox`/`Calendar` của gói (`focus-visible`,
@@ -1332,9 +1584,17 @@ function TimePickerColumnItem(props) {
          * (`not-data-selected:`) thay vì để `data-selected:hover:` ghi đè lại: cùng kết quả trên
          * màn hình, nhưng cách cũ khiến `pnpm lint:a11y` ghép chữ hover `--accent-foreground`
          * với nền mục đang chọn (1,39:1 ở dark) — một cặp không bao giờ xuất hiện.
+         *
+         * ⚠ Khác thượng nguồn (3.1.0): mục bị khoá theo `min`/`max` mờ và không nhận chuột theo đúng
+         * khuôn mục vô hiệu của gói (`DropdownMenu`, `Select`, `Mention`…: `pointer-events-none` +
+         * `opacity-50`). Dùng `aria-disabled` chứ KHÔNG dùng `disabled` gốc: mục vẫn nhận focus, nên
+         * một cột bị khoá TOÀN BỘ vẫn là một điểm dừng Tab (mục đón rơi vào nó — `getColumnEntry`) mà
+         * trình đọc màn hình đọc là "không khả dụng", thay vì cả cột biến mất khỏi thứ tự Tab. Chọn
+         * thì không được: `onClick` chặn (Enter/Space), mũi tên lên/xuống bỏ qua.
          */
         "w-full rounded px-3 py-1.5 text-left text-sm not-data-selected:hover:bg-accent not-data-selected:hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background",
         "data-selected:bg-control-on data-selected:text-control-check",
+        "data-disabled:pointer-events-none data-disabled:opacity-50",
         className
       ),
       onClick,
@@ -1345,7 +1605,7 @@ function TimePickerColumnItem(props) {
 }
 function TimePickerHour(props) {
   const { asChild, format = "numeric", className, ...hourProps } = props;
-  const { is12Hour, hourStep, showSeconds, disabled, readOnly, labels } = useTimePickerContext(HOUR_NAME);
+  const { is12Hour, hourStep, showSeconds, disabled, readOnly, labels, timeRange } = useTimePickerContext(HOUR_NAME);
   const store = useStoreContext(HOUR_NAME);
   const value = useStore((state) => state.value);
   const timeValue = parseTimeString(value);
@@ -1364,38 +1624,32 @@ function TimePickerHour(props) {
   const onHourSelect = React.useCallback(
     (displayHour2) => {
       if (disabled || readOnly) return;
-      const now2 = /* @__PURE__ */ new Date();
-      const currentTime = timeValue ?? {};
-      let hour24 = displayHour2;
-      if (is12Hour) {
-        let currentPeriod;
-        if (timeValue?.period !== void 0) {
-          currentPeriod = timeValue.period;
-        } else if (timeValue?.hour !== void 0) {
-          currentPeriod = to12Hour(timeValue.hour).period;
-        } else {
-          currentPeriod = to12Hour(now2.getHours()).period;
-        }
-        hour24 = to24Hour(displayHour2, currentPeriod);
-      }
-      const newTime = { ...currentTime, hour: hour24 };
-      if (timeValue && timeValue.period !== void 0) {
-        newTime.period = timeValue.period;
-      }
-      if (newTime.minute === void 0) {
-        newTime.minute = now2.getMinutes();
-      }
-      if (showSeconds && newTime.second === void 0) {
-        newTime.second = now2.getSeconds();
-      }
-      const newValue = formatTimeValue(newTime, showSeconds);
+      const newTime = buildHourTime(
+        timeValue,
+        displayHour2,
+        is12Hour,
+        showSeconds,
+        getReferenceTime(timeRange, showSeconds)
+      );
+      const newValue = formatTimeValue(constrainTime(newTime, timeRange, showSeconds, "hour"), showSeconds);
       store.setState("value", newValue);
     },
-    [timeValue, showSeconds, is12Hour, disabled, readOnly, store]
+    [timeValue, showSeconds, is12Hour, disabled, readOnly, store, timeRange]
   );
-  const now = /* @__PURE__ */ new Date();
-  const referenceHour = timeValue?.hour ?? now.getHours();
+  const reference = getReferenceTime(timeRange, showSeconds);
+  const referenceHour = timeValue?.hour ?? reference.hour;
   const displayHour = is12Hour ? to12Hour(referenceHour).hour : referenceHour;
+  const items = hours.map((hour) => ({
+    value: hour,
+    selected: displayHour === hour,
+    disabled: !isSegmentAllowed(
+      buildHourTime(timeValue, hour, is12Hour, showSeconds, reference),
+      "hour",
+      timeRange,
+      showSeconds
+    )
+  }));
+  const entry = getColumnEntry(items);
   const HourPrimitive = asChild ? Slot : TimePickerColumn;
   return /* @__PURE__ */ jsx(
     HourPrimitive,
@@ -1404,22 +1658,24 @@ function TimePickerHour(props) {
       "aria-label": labels.hour,
       ...hourProps,
       className: cn("scrollbar-none flex max-h-[200px] flex-col gap-1 overflow-y-auto p-1", className),
-      children: hours.map((hour) => /* @__PURE__ */ jsx(
+      children: items.map((item) => /* @__PURE__ */ jsx(
         TimePickerColumnItem,
         {
-          value: hour,
-          selected: displayHour === hour,
+          value: item.value,
+          selected: item.selected,
+          disabled: item.disabled,
+          tabIndex: item === entry ? 0 : -1,
           format,
-          onClick: () => onHourSelect(hour)
+          onClick: () => onHourSelect(item.value)
         },
-        hour
+        item.value
       ))
     }
   );
 }
 function TimePickerMinute(props) {
   const { asChild, format = "2-digit", className, ...minuteProps } = props;
-  const { minuteStep, showSeconds, disabled, readOnly, labels } = useTimePickerContext(MINUTE_NAME);
+  const { minuteStep, showSeconds, disabled, readOnly, labels, timeRange } = useTimePickerContext(MINUTE_NAME);
   const store = useStoreContext(MINUTE_NAME);
   const value = useStore((state) => state.value);
   const timeValue = parseTimeString(value);
@@ -1427,23 +1683,26 @@ function TimePickerMinute(props) {
   const onMinuteSelect = React.useCallback(
     (minute) => {
       if (disabled || readOnly) return;
-      const now2 = /* @__PURE__ */ new Date();
-      const currentTime = timeValue ?? {};
-      const newTime = { ...currentTime, minute };
-      if (newTime.hour === void 0) {
-        newTime.hour = now2.getHours();
-      }
-      if (showSeconds && newTime.second === void 0) {
-        newTime.second = now2.getSeconds();
-      }
-      const newValue = formatTimeValue(newTime, showSeconds);
+      const newTime = buildMinuteTime(timeValue, minute, showSeconds, getReferenceTime(timeRange, showSeconds));
+      const newValue = formatTimeValue(constrainTime(newTime, timeRange, showSeconds, "minute"), showSeconds);
       store.setState("value", newValue);
     },
-    [timeValue, showSeconds, disabled, readOnly, store]
+    [timeValue, showSeconds, disabled, readOnly, store, timeRange]
   );
   const MinutePrimitive = asChild ? Slot : TimePickerColumn;
-  const now = /* @__PURE__ */ new Date();
-  const referenceMinute = timeValue?.minute ?? now.getMinutes();
+  const reference = getReferenceTime(timeRange, showSeconds);
+  const referenceMinute = timeValue?.minute ?? reference.minute;
+  const items = minutes.map((minute) => ({
+    value: minute,
+    selected: referenceMinute === minute,
+    disabled: !isSegmentAllowed(
+      buildMinuteTime(timeValue, minute, showSeconds, reference),
+      "minute",
+      timeRange,
+      showSeconds
+    )
+  }));
+  const entry = getColumnEntry(items);
   return /* @__PURE__ */ jsx(
     MinutePrimitive,
     {
@@ -1451,22 +1710,24 @@ function TimePickerMinute(props) {
       "aria-label": labels.minute,
       ...minuteProps,
       className: cn("scrollbar-none flex max-h-[200px] flex-col gap-1 overflow-y-auto p-1", className),
-      children: minutes.map((minute) => /* @__PURE__ */ jsx(
+      children: items.map((item) => /* @__PURE__ */ jsx(
         TimePickerColumnItem,
         {
-          value: minute,
-          selected: referenceMinute === minute,
+          value: item.value,
+          selected: item.selected,
+          disabled: item.disabled,
+          tabIndex: item === entry ? 0 : -1,
           format,
-          onClick: () => onMinuteSelect(minute)
+          onClick: () => onMinuteSelect(item.value)
         },
-        minute
+        item.value
       ))
     }
   );
 }
 function TimePickerSecond(props) {
   const { asChild, format = "2-digit", className, ...secondProps } = props;
-  const { secondStep, disabled, readOnly, labels } = useTimePickerContext(SECOND_NAME);
+  const { secondStep, showSeconds, disabled, readOnly, labels, timeRange } = useTimePickerContext(SECOND_NAME);
   const store = useStoreContext(SECOND_NAME);
   const value = useStore((state) => state.value);
   const timeValue = parseTimeString(value);
@@ -1474,23 +1735,21 @@ function TimePickerSecond(props) {
   const onSecondSelect = React.useCallback(
     (second) => {
       if (disabled || readOnly) return;
-      const now2 = /* @__PURE__ */ new Date();
-      const currentTime = timeValue ?? {};
-      const newTime = { ...currentTime, second };
-      if (newTime.hour === void 0) {
-        newTime.hour = now2.getHours();
-      }
-      if (newTime.minute === void 0) {
-        newTime.minute = now2.getMinutes();
-      }
-      const newValue = formatTimeValue(newTime, true);
+      const newTime = buildSecondTime(timeValue, second, getReferenceTime(timeRange, showSeconds));
+      const newValue = formatTimeValue(constrainTime(newTime, timeRange, showSeconds, "second"), true);
       store.setState("value", newValue);
     },
-    [timeValue, disabled, readOnly, store]
+    [timeValue, showSeconds, disabled, readOnly, store, timeRange]
   );
   const SecondPrimitive = asChild ? Slot : TimePickerColumn;
-  const now = /* @__PURE__ */ new Date();
-  const referenceSecond = timeValue?.second ?? now.getSeconds();
+  const reference = getReferenceTime(timeRange, showSeconds);
+  const referenceSecond = timeValue?.second ?? reference.second;
+  const items = seconds.map((second) => ({
+    value: second,
+    selected: referenceSecond === second,
+    disabled: !isSegmentAllowed(buildSecondTime(timeValue, second, reference), "second", timeRange, showSeconds)
+  }));
+  const entry = getColumnEntry(items);
   return /* @__PURE__ */ jsx(
     SecondPrimitive,
     {
@@ -1498,49 +1757,51 @@ function TimePickerSecond(props) {
       "aria-label": labels.second,
       ...secondProps,
       className: cn("scrollbar-none flex max-h-[200px] flex-col gap-1 overflow-y-auto p-1", className),
-      children: seconds.map((second) => /* @__PURE__ */ jsx(
+      children: items.map((item) => /* @__PURE__ */ jsx(
         TimePickerColumnItem,
         {
-          value: second,
-          selected: referenceSecond === second,
+          value: item.value,
+          selected: item.selected,
+          disabled: item.disabled,
+          tabIndex: item === entry ? 0 : -1,
           format,
-          onClick: () => onSecondSelect(second)
+          onClick: () => onSecondSelect(item.value)
         },
-        second
+        item.value
       ))
     }
   );
 }
 function TimePickerPeriod(props) {
   const { asChild, className, ...periodProps } = props;
-  const { is12Hour, showSeconds, disabled, readOnly, labels } = useTimePickerContext(PERIOD_NAME);
+  const { is12Hour, showSeconds, disabled, readOnly, labels, timeRange } = useTimePickerContext(PERIOD_NAME);
   const store = useStoreContext(PERIOD_NAME);
   const value = useStore((state) => state.value);
   const timeValue = parseTimeString(value);
   const onPeriodToggle = React.useCallback(
     (period) => {
       if (disabled || readOnly) return;
-      const now2 = /* @__PURE__ */ new Date();
-      const currentTime = timeValue ?? {};
-      const currentHour = currentTime.hour !== void 0 ? currentTime.hour : now2.getHours();
-      const currentDisplay = to12Hour(currentHour);
-      const new24Hour = to24Hour(currentDisplay.hour, period);
-      const newTime = { ...currentTime, hour: new24Hour };
-      if (newTime.minute === void 0) {
-        newTime.minute = now2.getMinutes();
-      }
-      if (showSeconds && newTime.second === void 0) {
-        newTime.second = now2.getSeconds();
-      }
-      const newValue = formatTimeValue(newTime, showSeconds);
+      const newTime = buildPeriodTime(timeValue, period, showSeconds, getReferenceTime(timeRange, showSeconds));
+      const newValue = formatTimeValue(constrainTime(newTime, timeRange, showSeconds, "period"), showSeconds);
       store.setState("value", newValue);
     },
-    [timeValue, showSeconds, disabled, readOnly, store]
+    [timeValue, showSeconds, disabled, readOnly, store, timeRange]
   );
   if (!is12Hour) return null;
-  const now = /* @__PURE__ */ new Date();
-  const referenceHour = timeValue?.hour ?? now.getHours();
+  const reference = getReferenceTime(timeRange, showSeconds);
+  const referenceHour = timeValue?.hour ?? reference.hour;
   const currentPeriod = to12Hour(referenceHour).period;
+  const items = PERIODS.map((period) => ({
+    value: period,
+    selected: currentPeriod === period,
+    disabled: !isSegmentAllowed(
+      buildPeriodTime(timeValue, period, showSeconds, reference),
+      "period",
+      timeRange,
+      showSeconds
+    )
+  }));
+  const entry = getColumnEntry(items);
   const PeriodPrimitive = asChild ? Slot : TimePickerColumn;
   return /* @__PURE__ */ jsx(
     PeriodPrimitive,
@@ -1549,15 +1810,17 @@ function TimePickerPeriod(props) {
       "aria-label": labels.period,
       ...periodProps,
       className: cn("flex flex-col gap-1 p-1", className),
-      children: PERIODS.map((period) => /* @__PURE__ */ jsx(
+      children: items.map((item) => /* @__PURE__ */ jsx(
         TimePickerColumnItem,
         {
-          value: period,
-          selected: currentPeriod === period,
-          onClick: () => onPeriodToggle(period),
-          children: getPeriodLabel(period, labels)
+          value: item.value,
+          selected: item.selected,
+          disabled: item.disabled,
+          tabIndex: item === entry ? 0 : -1,
+          onClick: () => onPeriodToggle(item.value),
+          children: getPeriodLabel(item.value, labels)
         },
-        period
+        item.value
       ))
     }
   );