stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/time_picker_controller.js

@@ -1,13 +1,9 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/time_picker_controller.ts
-
-// src/utils/logical_scroll.ts
 function isRtl(element) {
   return window.getComputedStyle(element).direction === "rtl";
 }
 
-// src/utils/arrow_step.ts
 function logicalArrowKey(key, element) {
   if (key !== "ArrowRight" && key !== "ArrowLeft") return key;
   if (!isRtl(element)) return key;
@@ -17,8 +13,108 @@ function isReservedArrowChord(event, allow = []) {
   if (!event.key.startsWith("Arrow")) return false;
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
+function hasModifierChord(event) {
+  return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
+
+function setAttributeIfChanged(element, name, value, beforeWrite) {
+  if (element.getAttribute(name) === value) return false;
+  beforeWrite?.();
+  if (value === null) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+  return true;
+}
+
+var AuthoredMutationWatcher = class {
+  #onAuthored;
+  #claims = null;
+  #observer = null;
+  constructor(onAuthored) {
+    this.#onAuthored = onAuthored;
+  }
+  observe(root, options) {
+    this.disconnect();
+    const observer = new MutationObserver((records) => {
+      if (this.#observer !== observer) return;
+      const authored = this.#filter(records);
+      if (authored.length > 0) this.#onAuthored(authored);
+    });
+    this.#observer = observer;
+    this.#claims = { attributes: /* @__PURE__ */ new Map(), children: /* @__PURE__ */ new Map() };
+    observer.observe(root, {
+      attributes: true,
+      attributeFilter: [...options.attributes],
+      subtree: options.subtree ?? false,
+      childList: options.childList ?? false
+    });
+    if (options.ancestorAttributes) {
+      let ancestor = root.parentElement;
+      while (ancestor) {
+        observer.observe(ancestor, {
+          attributes: true,
+          attributeFilter: [...options.ancestorAttributes]
+        });
+        ancestor = ancestor.parentElement;
+      }
+    }
+  }
+  claim(target, name, value) {
+    const claims = this.#claims?.attributes;
+    let attributes = claims?.get(target);
+    if (!attributes) {
+      attributes = /* @__PURE__ */ new Map();
+      claims?.set(target, attributes);
+    }
+    const pending = attributes.get(name);
+    attributes.set(name, { value, count: (pending?.count ?? 0) + 1 });
+  }
+  claimCurrent(target, name) {
+    this.claim(target, name, target.getAttribute(name));
+  }
+  claimChildList(target, added, removed) {
+    const claims = this.#claims?.children;
+    const pending = claims?.get(target) ?? { added: /* @__PURE__ */ new Map(), removed: /* @__PURE__ */ new Map() };
+    for (const node of added) pending.added.set(node, (pending.added.get(node) ?? 0) + 1);
+    for (const node of removed) pending.removed.set(node, (pending.removed.get(node) ?? 0) + 1);
+    claims?.set(target, pending);
+  }
+  take() {
+    return this.#filter(this.#observer?.takeRecords() ?? []);
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#claims = null;
+  }
+  #filter(records) {
+    const authored = records.filter((record) => !this.#consume(record));
+    this.#claims?.attributes.clear();
+    this.#claims?.children.clear();
+    return authored;
+  }
+  #consume(record) {
+    if (record.type === "attributes") {
+      const target = record.target;
+      const pending2 = this.#claims?.attributes.get(target)?.get(record.attributeName);
+      if (!pending2 || pending2.count === 0 || target.getAttribute(record.attributeName) !== pending2.value) {
+        return false;
+      }
+      pending2.count -= 1;
+      return true;
+    }
+    const pending = this.#claims?.children.get(record.target);
+    if (!pending) return false;
+    const added = [...record.addedNodes];
+    const removed = [...record.removedNodes];
+    if (added.some((node) => !pending.added.get(node)) || removed.some((node) => !pending.removed.get(node))) {
+      return false;
+    }
+    for (const node of added) pending.added.set(node, (pending.added.get(node) ?? 0) - 1);
+    for (const node of removed) pending.removed.set(node, (pending.removed.get(node) ?? 0) - 1);
+    return true;
+  }
+};
 
-// src/utils/field_mirror.ts
 function writeField(field, value) {
   if (field.value === value) return false;
   field.value = value;
@@ -28,27 +124,36 @@ function commitField(target) {
   target.dispatchEvent(new Event("change", { bubbles: true }));
 }
 
-// src/utils/microtask_coalescer.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  get pending() {
+    return this.#queued;
+  }
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -61,93 +166,183 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/utils/target_selector.ts
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var MoveCounter = class {
+  #sequence = 0;
+  record() {
+    this.#sequence += 1;
+    return this.#sequence;
+  }
+  isLatest(token) {
+    return token === this.#sequence;
+  }
+};
+
+var NUMBER_BOUNDS = {
+  positive: { finite: true, exclusiveMin: 0 }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function targetSelector(identifier, name) {
   return `[data-${identifier}-target~="${name}"]`;
 }
 
-// src/controllers/time_picker_controller.ts
 var AM = 0;
 var PM = 1;
 var SECONDS_PER_MINUTE = 60;
 var SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE;
 var SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR;
-var hasModifier = (event) => event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
-var TimePickerController = class extends Controller {
+var TimePickerController = class _TimePickerController extends Controller {
+  #numbers = new NumberValueReader();
+  #moves = new MoveCounter();
+  #connectionGeneration = 0;
+  #move = 0;
   static targets = ["segment", "field"];
   static values = {
     hourCycle: { type: Number, default: 24 },
+    hour12ZeroBased: { type: Boolean, default: false },
     step: { type: Number, default: 1 },
     seconds: { type: Boolean, default: false },
-    wrap: { type: Boolean, default: true }
+    wrap: { type: Boolean, default: true },
+    amLabel: { type: String, default: "AM" },
+    pmLabel: { type: String, default: "PM" }
+  };
+  static valueConstraints = {
+    hourCycle: { finite: true, allowedValues: [12, 24] },
+    step: NUMBER_BOUNDS.positive
   };
   static actions = ["onKeydown"];
   static events = ["change", "reconcile"];
-  /**
-   * Collapses target, Value, and retained-attribute morphs into one render that
-   * dispatches no `change`.
-   */
-  #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());
-  /** Canonical state; the displayed hour and meridiem are derived from this value. */
+  #reconcile = new MorphRenderWatcher(() => this.#reconcileDom());
   #state = { hour: 0, minute: 0, second: 0 };
-  /** Direct-entry digit buffer and the segment it belongs to. */
   #typeBuffer = "";
   #typeSegment = null;
-  /** Last composed value, used to suppress duplicate user notifications. */
   #lastValue = "";
-  #observer = null;
-  #connected = false;
+  #renderedHourMode = null;
+  #renderedSegments = /* @__PURE__ */ new WeakSet();
+  #authoredSegments = /* @__PURE__ */ new Set();
+  #observer = new AuthoredMutationWatcher((records) => {
+    if (!this.#recordAuthoredSegments(records)) return;
+    this.#reconcile.schedule();
+  });
   #domDirty = false;
-  /** Seeds state from the DOM, renders canonical ARIA, and starts morph observation. */
+  #listeners = new ListenerSet();
   connect() {
-    this.#connected = true;
-    this.#reconcile.activate();
-    this.element.addEventListener("focusout", this.#onFocusOut);
+    this.#reconcile.observe(this.element);
+    this.#listeners.add(this.element, "focusout", this.#onFocusOut);
     this.#domDirty = false;
     this.#adoptDomState();
     this.#render();
     this.#observeMutations();
   }
-  /** Releases the observer, listener, queued reconciliation, and transient input state. */
   disconnect() {
-    this.#connected = false;
-    this.#reconcile.cancel();
-    this.element.removeEventListener("focusout", this.#onFocusOut);
-    this.#observer?.disconnect();
-    this.#observer = null;
+    this.#connectionGeneration += 1;
+    this.#reconcile.disconnect();
+    this.#listeners.dispose();
+    this.#observer.disconnect();
     this.#domDirty = false;
+    this.#renderedHourMode = null;
+    this.#renderedSegments = /* @__PURE__ */ new WeakSet();
+    this.#authoredSegments.clear();
     this.#clearTypeBuffer();
     this.#lastValue = "";
   }
-  /** Re-renders the canonical instant when 12/24-hour presentation changes at runtime. */
   hourCycleValueChanged() {
     this.#reconcile.schedule();
   }
-  /** Recomposes the optional seconds portion after a runtime Value change. */
+  hour12ZeroBasedValueChanged() {
+    this.#reconcile.schedule();
+  }
   secondsValueChanged() {
     this.#reconcile.schedule();
   }
-  /** Adopts a segment inserted or replaced by a Turbo morph. */
+  amLabelValueChanged() {
+    this.#reconcile.schedule();
+  }
+  pmLabelValueChanged() {
+    this.#reconcile.schedule();
+  }
   segmentTargetConnected() {
     this.#domDirty = true;
-    this.#clearTypeBuffer();
     this.#reconcile.schedule();
   }
-  /** Rebuilds state after a segment leaves the retained controller element. */
-  segmentTargetDisconnected() {
+  segmentTargetDisconnected(segment) {
+    if (segment && !this.segmentTargets.includes(segment)) this.#renderedSegments.delete(segment);
     this.#domDirty = true;
-    this.#clearTypeBuffer();
     this.#reconcile.schedule();
   }
-  /** Reflects the current composed value into a field added or replaced at runtime. */
   fieldTargetConnected() {
     this.#reconcile.schedule();
   }
-  /** Reconciles silently when the optional field leaves at runtime. */
   fieldTargetDisconnected() {
     this.#reconcile.schedule();
   }
-  /** Handles APG stepping, inter-segment focus moves, jumps, and direct entry. */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
     const segment = event.target?.closest(
@@ -157,7 +352,9 @@ var TimePickerController = class extends Controller {
     const kind = this.#kindOf(segment);
     if (!kind) return;
     const key = logicalArrowKey(event.key, this.element);
-    if ((key === "Home" || key === "End") && hasModifier(event)) return;
+    if ((key === "Home" || key === "End") && hasModifierChord(event)) return;
+    if (this.#adoptPendingDom()) this.#reconcile.schedule();
+    if (this.#renderedHourMode !== this.#hourMode) this.#clearTypeBuffer();
     switch (key) {
       case "ArrowUp":
         event.preventDefault();
@@ -186,7 +383,7 @@ var TimePickerController = class extends Controller {
         this.#commitRender();
         break;
       default:
-        if (kind !== "meridiem" && /^[0-9]$/.test(event.key) && !hasModifier(event)) {
+        if (kind !== "meridiem" && /^[0-9]$/.test(event.key) && !event.ctrlKey && !event.altKey && !event.metaKey) {
           event.preventDefault();
           this.#typeDigit(segment, kind, event.key);
           return;
@@ -195,7 +392,6 @@ var TimePickerController = class extends Controller {
     }
     this.#clearTypeBuffer();
   }
-  /** Clears direct-entry state when Tab, Shift+Tab, or pointer focus leaves a segment. */
   #onFocusOut = (event) => {
     const segment = event.target?.closest(
       targetSelector(this.identifier, "segment")
@@ -203,13 +399,11 @@ var TimePickerController = class extends Controller {
     if (!segment || !this.segmentTargets.includes(segment)) return;
     this.#clearTypeBuffer();
   };
-  /** Uses the normalized positive-integer minute step; other segments step by one. */
   #delta(kind) {
     if (kind !== "minute") return 1;
-    const step = Math.trunc(this.stepValue);
-    return Number.isFinite(step) && step > 0 ? step : 1;
+    const step = Math.trunc(this.#safeStep);
+    return step > 0 ? step : 1;
   }
-  /** Mutates one complete action and then renders/notifies its final value once. */
   #step(kind, delta) {
     if (kind === "meridiem" && this.wrapValue) {
       this.#state.hour = modulo(this.#state.hour + 12, 24);
@@ -225,7 +419,6 @@ var TimePickerController = class extends Controller {
     }
     this.#commitRender();
   }
-  /** Accumulates a typed digit, rendering once and advancing after completion. */
   #typeDigit(segment, kind, digit) {
     if (this.#typeSegment !== kind) this.#typeBuffer = "";
     this.#typeSegment = kind;
@@ -233,34 +426,46 @@ var TimePickerController = class extends Controller {
     const candidate = Number(`${this.#typeBuffer}${digit}`);
     this.#typeBuffer = candidate <= max ? `${this.#typeBuffer}${digit}` : digit;
     this.#setDisplayed(kind, Number(this.#typeBuffer));
-    this.#commitRender();
+    this.#commitRender(true);
     if (this.#typeBuffer.length >= 2 || Number(this.#typeBuffer) * 10 > max) {
       this.#clearTypeBuffer();
       this.#focusSibling(segment, 1);
     }
   }
-  /** Moves focus to the previous/next valid segment, if one exists. */
   #focusSibling(segment, direction) {
     const segments = this.segmentTargets.filter((candidate) => this.#kindOf(candidate) !== null);
     const index = segments.indexOf(segment);
     segments[index + direction]?.focus();
   }
-  /** Clears the direct-entry buffer and its owning segment together. */
   #clearTypeBuffer() {
     this.#typeBuffer = "";
     this.#typeSegment = null;
   }
-  /** Reconciles one coalesced target, Value, or retained-attribute mutation batch. */
-  #reconcileDom() {
-    if (this.#domDirty) {
-      this.#domDirty = false;
-      this.#clearTypeBuffer();
-      this.#adoptDomState();
+  #adoptPendingDom() {
+    this.#recordAuthoredSegments(this.#observer.take());
+    if (!this.#domDirty) return false;
+    this.#domDirty = false;
+    this.#clearTypeBuffer();
+    this.#adoptDomState();
+    return true;
+  }
+  #recordAuthoredSegments(records) {
+    let changed = false;
+    for (const { target } of records) {
+      if (!(target instanceof HTMLElement) || !this.segmentTargets.includes(target)) continue;
+      this.#authoredSegments.add(target);
+      changed = true;
     }
+    if (changed) this.#domDirty = true;
+    return changed;
+  }
+  #reconcileDom() {
+    this.#adoptPendingDom();
     this.#render();
   }
-  /** Rebuilds canonical state from the targets; an absent hour represents midnight. */
   #adoptDomState() {
+    const mode = this.#hourMode;
+    const presentationChanged = this.#renderedHourMode !== null && this.#renderedHourMode !== mode;
     let displayedHour = 0;
     let meridiem = AM;
     let minute = 0;
@@ -268,58 +473,56 @@ var TimePickerController = class extends Controller {
     for (const segment of this.segmentTargets) {
       const kind = this.#kindOf(segment);
       if (!kind) continue;
-      const value = this.#authoredValue(segment, kind);
+      const retained = presentationChanged && this.#renderedSegments.has(segment) && !this.#authoredSegments.has(segment);
+      let value;
+      if (retained && kind === "hour") {
+        value = mode === "h23" ? this.#state.hour : this.#state.hour % 12;
+      } else if (retained && kind === "meridiem") {
+        value = this.#state.hour >= 12 ? PM : AM;
+      } else {
+        value = this.#authoredValue(segment, kind);
+      }
       if (kind === "hour") displayedHour = value;
       else if (kind === "minute") minute = value;
       else if (kind === "second") second = value;
       else meridiem = value;
     }
     this.#state = {
-      hour: this.hourCycleValue === 12 ? displayedHour % 12 + (meridiem === PM ? 12 : 0) : displayedHour,
+      hour: this.#safeHourCycle === 12 ? displayedHour % 12 + (meridiem === PM ? 12 : 0) : displayedHour,
       minute,
       second
     };
+    this.#authoredSegments.clear();
   }
-  /** Reads and integer-clamps one authored `aria-valuenow`. */
   #authoredValue(segment, kind) {
     const raw = Number(segment.getAttribute("aria-valuenow"));
     const { min, max } = this.#bounds(kind);
     if (!Number.isFinite(raw)) return min;
     return Math.min(max, Math.max(min, Math.trunc(raw)));
   }
-  /** Writes a displayed segment value back into canonical state without rendering. */
   #setDisplayed(kind, raw) {
     const { min, max } = this.#bounds(kind);
     const value = Math.min(max, Math.max(min, Math.trunc(raw)));
     if (kind === "hour") {
-      this.#state.hour = this.hourCycleValue === 12 ? value % 12 + (this.#state.hour >= 12 ? 12 : 0) : value;
+      this.#state.hour = this.#safeHourCycle === 12 ? value % 12 + (this.#state.hour >= 12 ? 12 : 0) : value;
     } else if (kind === "minute" || kind === "second") {
       this.#state[kind] = value;
     } else {
       this.#state.hour = this.#state.hour % 12 + (value === PM ? 12 : 0);
     }
   }
-  /** Converts seconds with day wrapping into the canonical three-unit state. */
   #setFromSeconds(raw) {
     const seconds = modulo(raw, SECONDS_PER_DAY);
     this.#state.hour = Math.floor(seconds / SECONDS_PER_HOUR);
     this.#state.minute = Math.floor(seconds % SECONDS_PER_HOUR / SECONDS_PER_MINUTE);
     this.#state.second = seconds % SECONDS_PER_MINUTE;
   }
-  /** Reflects canonical state to every segment without dispatching user events. */
-  #renderSegments() {
-    this.#withoutObservation(() => {
-      for (const segment of this.segmentTargets) this.#renderSegment(segment);
-    });
+  #renderSegments(preserveTypeBuffer = false) {
+    const mode = this.#hourMode;
+    if (this.#renderedHourMode !== mode && !preserveTypeBuffer) this.#clearTypeBuffer();
+    this.#renderedHourMode = mode;
+    for (const segment of this.segmentTargets) this.#renderSegment(segment);
   }
-  /**
-   * Reflects canonical state during connection or DOM reconciliation.
-   *
-   * No user edit reaches here, so `change` never fires from this path. A pass
-   * that moves the committed value reports `reconcile` instead.
-   *
-   * @stimeoRenderRoot
-   */
   #render() {
     this.#renderSegments();
     const value = this.#composedValue;
@@ -327,53 +530,61 @@ var TimePickerController = class extends Controller {
     this.#writeField(value);
     this.#lastValue = value;
     if (previous !== "" && value !== previous) {
+      this.#move = this.#moves.record();
       this.dispatch("reconcile", { detail: { value } });
     }
   }
-  /** Reflects one completed user action and dispatches its final change exactly once. */
-  #commitRender() {
-    this.#renderSegments();
+  #commitRender(preserveTypeBuffer = false) {
+    const generation = this.#connectionGeneration;
+    this.#renderSegments(preserveTypeBuffer);
     const value = this.#composedValue;
-    if (this.#writeField(value)) commitField(this.fieldTarget);
-    if (value !== this.#lastValue) this.dispatch("change", { detail: { value } });
+    const changed = value !== this.#lastValue;
     this.#lastValue = value;
+    if (changed) this.#move = this.#moves.record();
+    const move = this.#move;
+    if (this.#writeField(value)) commitField(this.fieldTarget);
+    if (generation !== this.#connectionGeneration || !this.#moves.isLatest(move)) return;
+    if (changed) this.dispatch("change", { detail: { value } });
   }
-  /** Reflects one segment's value and controller-owned ARIA bounds/text. */
   #renderSegment(segment) {
     const kind = this.#kindOf(segment);
     if (!kind) return;
+    this.#renderedSegments.add(segment);
     const value = this.#displayValue(kind);
-    const text = kind === "meridiem" ? value === PM ? "PM" : "AM" : pad(value);
+    const text = kind === "meridiem" ? value === PM ? this.pmLabelValue : this.amLabelValue : pad(value);
     const { min, max } = this.#bounds(kind);
-    segment.setAttribute("aria-valuenow", String(value));
+    const serialized = String(value);
+    setAttributeIfChanged(segment, "aria-valuenow", serialized, () => {
+      this.#observer.claim(segment, "aria-valuenow", serialized);
+    });
     segment.setAttribute("aria-valuetext", text);
     segment.setAttribute("aria-valuemin", String(min));
     segment.setAttribute("aria-valuemax", String(max));
     segment.textContent = text;
   }
-  /** Writes a composed value to the optional form field and reports whether it changed. */
   #writeField(value) {
     return this.hasFieldTarget && writeField(this.fieldTarget, value);
   }
-  /** The canonical form value composed as `HH:MM[:SS]`. */
   get #composedValue() {
     const parts = [pad(this.#state.hour), pad(this.#state.minute)];
     if (this.secondsValue) parts.push(pad(this.#state.second));
     return parts.join(":");
   }
-  /** Returns a canonical unit in the presentation form exposed by its segment. */
   #displayValue(kind) {
     if (kind === "hour") {
-      return this.hourCycleValue === 12 ? this.#state.hour % 12 || 12 : this.#state.hour;
+      const mode = this.#hourMode;
+      if (mode === "h23") return this.#state.hour;
+      const hour = this.#state.hour % 12;
+      return mode === "h11" ? hour : hour || 12;
     }
     if (kind === "meridiem") return this.#state.hour >= 12 ? PM : AM;
     return this.#state[kind];
   }
-  /** The inclusive controller-owned bounds for a segment kind. */
   #bounds(kind) {
     switch (kind) {
       case "hour":
-        return this.hourCycleValue === 12 ? { min: 1, max: 12 } : { min: 0, max: 23 };
+        if (this.#hourMode === "h23") return { min: 0, max: 23 };
+        return this.#hourMode === "h11" ? { min: 0, max: 11 } : { min: 1, max: 12 };
       case "minute":
       case "second":
         return { min: 0, max: 59 };
@@ -381,39 +592,12 @@ var TimePickerController = class extends Controller {
         return { min: AM, max: PM };
     }
   }
-  /** Watches retained segment state while excluding this controller's own reflections. */
   #observeMutations() {
-    const observer = new MutationObserver((records) => {
-      const changed = records.some(
-        ({ target }) => target instanceof HTMLElement && this.segmentTargets.includes(target)
-      );
-      if (!changed) return;
-      this.#domDirty = true;
-      this.#clearTypeBuffer();
-      this.#reconcile.schedule();
-    });
-    this.#observer = observer;
-    this.#observeWith(observer);
-  }
-  /** Registers retained attribute observation on the controller subtree. */
-  #observeWith(observer) {
-    observer.observe(this.element, {
+    this.#observer.observe(this.element, {
       subtree: true,
-      attributes: true,
-      attributeFilter: ["aria-valuenow", "data-segment"]
+      attributes: ["aria-valuenow", "data-segment"]
     });
   }
-  /** Temporarily pauses observation so derived ARIA writes cannot become DOM input. */
-  #withoutObservation(run) {
-    const observer = this.#observer;
-    observer?.disconnect();
-    try {
-      run();
-    } finally {
-      if (observer && this.#connected) this.#observeWith(observer);
-    }
-  }
-  /** Reads a segment's declared kind, or null when absent/invalid. */
   #kindOf(segment) {
     const kind = segment.getAttribute("data-segment");
     if (kind === "hour" || kind === "minute" || kind === "second" || kind === "meridiem") {
@@ -421,10 +605,31 @@ var TimePickerController = class extends Controller {
     }
     return null;
   }
-  /** Canonical state as seconds since the start of its nominal day. */
   get #secondsOfDay() {
     return this.#state.hour * SECONDS_PER_HOUR + this.#state.minute * SECONDS_PER_MINUTE + this.#state.second;
   }
+  get #hourMode() {
+    if (this.#safeHourCycle !== 12) return "h23";
+    return this.hour12ZeroBasedValue ? "h11" : "h12";
+  }
+  get #safeHourCycle() {
+    return this.#numbers.read(
+      this,
+      "hourCycle",
+      this.hourCycleValue,
+      _TimePickerController.values.hourCycle.default,
+      _TimePickerController.valueConstraints.hourCycle
+    );
+  }
+  get #safeStep() {
+    return this.#numbers.read(
+      this,
+      "step",
+      this.stepValue,
+      _TimePickerController.values.step.default,
+      _TimePickerController.valueConstraints.step
+    );
+  }
 };
 function modulo(value, modulus) {
   return (value % modulus + modulus) % modulus;
@@ -434,5 +639,4 @@ function pad(value) {
 }
 
 export { TimePickerController };
-//# sourceMappingURL=time_picker_controller.js.map
 //# sourceMappingURL=time_picker_controller.js.map