@radix-ng/primitives 1.0.0-beta.1 → 1.0.0-beta.2

package/fesm2022/radix-ng-primitives-core.mjs

@@ -183,16 +183,25 @@ function snapValueToStep(value, min, max, step) {
 
 // Thanks for idea.
 // https://github.com/unovue/reka-ui/blob/v2/packages/core/src/shared/createContext.ts
+/**
+ * Base URL of the documentation site. Each primitive's docs are also served as plain
+ * Markdown at `/<section>/<slug>.md`, which both humans and AI agents can open.
+ */
+const DOCS_BASE_URL = 'https://radix-ng.com';
 /**
  * Creates a context with injector and provider functions for a given type
  * @template T The type of the context value
  * @param description Descriptive string for the context (used in token creation)
+ * @param docs Documentation path for the owning primitive (e.g. `'components/accordion'`),
+ *   appended to the missing-context error as a link to the required anatomy
  * @returns A tuple containing:
  *   - injectContext: Function to retrieve the context value
  *   - provideContext: Function to create a provider for the context
  */
-function createContext(description) {
-    const CONTEXT_TOKEN = new InjectionToken(`${description}Context`);
+function createContext(description, docs) {
+    // Normalize so both `'FooRoot'` and `'FooRootContext'` read as `FooRootContext`.
+    const contextName = `${description.replace(/\s*Context$/, '')}Context`;
+    const CONTEXT_TOKEN = new InjectionToken(contextName);
     /**
      * Retrieves the context value from Angular's dependency injection
      * @param optional If true, returns null when context is not provided instead of throwing
@@ -205,8 +214,9 @@ function createContext(description) {
         // provided factory that returns null/undefined for the non-optional case.
         const value = inject(CONTEXT_TOKEN, { optional: true });
         if (value == null && !optional) {
-            throw new Error(`No \`${description}Context\` found. A part of the \`${description}\` primitive ` +
-                `must be used inside its root (the directive that provides \`${description}Context\`).`);
+            const docsHint = docs ? ` See ${DOCS_BASE_URL}/${docs}.md for the required part hierarchy.` : '';
+            throw new Error(`No \`${contextName}\` found. This part must be placed inside the directive ` +
+                `that provides \`${contextName}\` (usually the primitive's root).${docsHint}`);
         }
         return value;
     };
@@ -375,6 +385,12 @@ function areAllDaysBetweenValid(start, end, isUnavailable, isDisabled) {
     }
     return true;
 }
+/**
+ * The granularities that require a time component (and therefore a `CalendarDateTime`
+ * rather than a `CalendarDate`). Single source of truth — used by both the default-date
+ * builder and the segment-value initializer.
+ */
+const TIME_GRANULARITIES = ['hour', 'minute', 'second'];
 /**
  * A helper function used throughout the various date builders
  * to generate a default `DateValue` using the `defaultValue`,
@@ -387,20 +403,25 @@ function areAllDaysBetweenValid(start, end, isUnavailable, isDisabled) {
  */
 function getDefaultDate(props) {
     const { defaultValue, defaultPlaceholder, granularity = 'day', locale = 'en' } = props;
-    if (Array.isArray(defaultValue) && defaultValue.length)
-        return defaultValue[defaultValue.length - 1].copy();
-    if (defaultValue && !Array.isArray(defaultValue))
+    if (Array.isArray(defaultValue)) {
+        // Multiple-selection calendars pass an array. The view follows the most recently
+        // selected date — consistent with calendar-root's value→placeholder sync. An empty
+        // array means "no selection", so fall through to the placeholder / today.
+        if (defaultValue.length)
+            return defaultValue[defaultValue.length - 1].copy();
+    }
+    else if (defaultValue) {
         return defaultValue.copy();
+    }
     if (defaultPlaceholder)
         return defaultPlaceholder.copy();
     const date = new Date();
     const year = date.getFullYear();
     const month = date.getMonth() + 1;
     const day = date.getDate();
-    const calendarDateTimeGranularities = ['hour', 'minute', 'second'];
     const defaultFormatter = new DateFormatter(locale);
     const calendar = createCalendar(defaultFormatter.resolvedOptions().calendar);
-    if (calendarDateTimeGranularities.includes(granularity ?? 'day'))
+    if (TIME_GRANULARITIES.includes(granularity ?? 'day'))
         return toCalendar(new CalendarDateTime(year, month, day, 0, 0, 0), calendar);
     return toCalendar(new CalendarDate(year, month, day), calendar);
 }
@@ -498,7 +519,10 @@ function getWeekNumber(date, locale = 'en-US', firstDayOfWeek) {
         const prevYearDate = new CalendarDate(date.year - 1, 12, 31);
         return getWeekNumber(prevYearDate, locale, firstDayOfWeek);
     }
-    const days = getDaysBetween(firstWeekStart, date);
+    // `getDaysBetween` is exclusive of both ends, so extend the end by a day to count the
+    // full span from `firstWeekStart` through `date` (otherwise every 7-day boundary is
+    // under-counted by one and the week number lags).
+    const days = getDaysBetween(firstWeekStart, date.add({ days: 1 }));
     // Week number is days divided by 7 plus 1
     return Math.floor(days.length / 7) + 1;
 }
@@ -511,6 +535,22 @@ const defaultPartOptions = {
     minute: 'numeric',
     second: 'numeric'
 };
+/**
+ * Constructing a `DateFormatter` (which wraps `Intl.DateTimeFormat`) is by far the most
+ * expensive operation here, and `createContent` formats every segment on each keystroke.
+ * Reuse instances keyed by locale + options — the set of distinct combinations is tiny and
+ * the instances are immutable.
+ */
+const formatterCache = new Map();
+function getDateFormatter(locale, options) {
+    const key = `${locale}|${JSON.stringify(options)}`;
+    let formatter = formatterCache.get(key);
+    if (!formatter) {
+        formatter = new DateFormatter(locale, options);
+        formatterCache.set(key, formatter);
+    }
+    return formatter;
+}
 /**
  * Creates a wrapper around the `DateFormatter`, which is
  * an improved version of the {@link Intl.DateTimeFormat} API,
@@ -528,7 +568,7 @@ function createFormatter(initialLocale, opts = {}) {
         return locale;
     }
     function custom(date, options) {
-        return new DateFormatter(locale, { ...opts, ...options }).format(date);
+        return getDateFormatter(locale, { ...opts, ...options }).format(date);
     }
     function selectedDate(date, includeTime = true) {
         if (hasTime(date) && includeTime) {
@@ -544,31 +584,31 @@ function createFormatter(initialLocale, opts = {}) {
         }
     }
     function fullMonthAndYear(date, options = {}) {
-        return new DateFormatter(locale, { ...opts, month: 'long', year: 'numeric', ...options }).format(date);
+        return getDateFormatter(locale, { ...opts, month: 'long', year: 'numeric', ...options }).format(date);
     }
     function fullMonth(date, options = {}) {
-        return new DateFormatter(locale, { ...opts, month: 'long', ...options }).format(date);
+        return getDateFormatter(locale, { ...opts, month: 'long', ...options }).format(date);
     }
     function fullYear(date, options = {}) {
-        return new DateFormatter(locale, { ...opts, year: 'numeric', ...options }).format(date);
+        return getDateFormatter(locale, { ...opts, year: 'numeric', ...options }).format(date);
     }
     function toParts(date, options) {
         if (isZonedDateTime(date)) {
-            return new DateFormatter(locale, {
+            return getDateFormatter(locale, {
                 ...opts,
                 ...options,
                 timeZone: date.timeZone
             }).formatToParts(toDate(date));
         }
         else {
-            return new DateFormatter(locale, { ...opts, ...options }).formatToParts(toDate(date));
+            return getDateFormatter(locale, { ...opts, ...options }).formatToParts(toDate(date));
         }
     }
     function dayOfWeek(date, length = 'narrow') {
-        return new DateFormatter(locale, { ...opts, weekday: length }).format(date);
+        return getDateFormatter(locale, { ...opts, weekday: length }).format(date);
     }
     function dayPeriod(date, hourCycle = undefined) {
-        const parts = new DateFormatter(locale, {
+        const parts = getDateFormatter(locale, {
             ...opts,
             hour: 'numeric',
             minute: 'numeric',
@@ -832,7 +872,6 @@ function normalizeHour12(hourCycle) {
     return undefined;
 }
 
-const calendarDateTimeGranularities = ['hour', 'minute', 'second'];
 function syncTimeSegmentValues(props) {
     return Object.fromEntries(TIME_SEGMENT_PARTS.map((part) => {
         if (part === 'dayPeriod')
@@ -840,7 +879,7 @@ function syncTimeSegmentValues(props) {
         return [part, props.value[part]];
     }));
 }
-function initializeSegmentValues(granularity) {
+function initializeSegmentValues(granularity, isTimeValue = false) {
     const initialParts = EDITABLE_SEGMENT_PARTS.map((part) => {
         if (part === 'dayPeriod')
             return [part, 'AM'];
@@ -848,12 +887,16 @@ function initializeSegmentValues(granularity) {
     }).filter(([key]) => {
         if (key === 'literal' || key === null)
             return false;
+        // A time-only field has no date segments, so they must not be seeded — otherwise they
+        // stay null forever and block committing the value (every segment must be filled).
+        if (isTimeValue && isDateSegmentPart(key))
+            return false;
         if (granularity === 'minute' && key === 'second')
             return false;
         if (granularity === 'hour' && (key === 'second' || key === 'minute'))
             return false;
         if (granularity === 'day')
-            return !calendarDateTimeGranularities.includes(key) && key !== 'dayPeriod';
+            return !TIME_GRANULARITIES.includes(key) && key !== 'dayPeriod';
         else
             return true;
     });
@@ -1055,6 +1098,20 @@ function getSegmentElements(parentElement) {
  */
 
 // https://github.com/unovue/reka-ui/blob/v2/packages/core/src/shared/date/useDateField.ts
+/** Convert a canonical 24-hour value (0-23) to its 12-hour clock equivalent (1-12). */
+function to12Hour(hour) {
+    const h = hour % 12;
+    return h === 0 ? 12 : h;
+}
+/** Combine a 12-hour clock value (1-12) with a day period into a canonical 24-hour value (0-23). */
+function to24Hour(hour, period) {
+    const h = hour % 12;
+    return period === 'PM' ? h + 12 : h;
+}
+/** The day period a canonical 24-hour value belongs to. */
+function dayPeriodForHour(hour) {
+    return hour >= 12 ? 'PM' : 'AM';
+}
 function commonSegmentAttrs(props) {
     return {
         role: 'spinbutton',
@@ -1067,120 +1124,79 @@ function commonSegmentAttrs(props) {
         style: 'caret-color: transparent;'
     };
 }
-function daySegmentAttrs(props) {
+/**
+ * Shared spinbutton attributes for the numeric segments (day/month/year/hour/minute/second).
+ * Each segment differs only in its field, bounds, label and optional value-text formatting.
+ */
+function numericSegmentAttrs(props, config) {
     const { segmentValues, placeholder } = props;
-    const isEmpty = segmentValues.day === null;
-    const date = segmentValues.day ? placeholder.set({ day: segmentValues.day }) : placeholder;
-    const valueNow = date.day;
-    const valueMin = 1;
-    const valueMax = getDaysInMonth(date);
-    const valueText = isEmpty ? 'Empty' : `${valueNow}`;
+    const { field } = config;
+    if (config.timePart && (!(field in segmentValues) || !(field in placeholder)))
+        return {};
+    const value = segmentValues[field];
+    const isEmpty = value == null;
+    const date = value != null ? placeholder.set({ [field]: value }) : placeholder;
+    const valueNow = date[field];
+    const valueMax = typeof config.valueMax === 'function' ? config.valueMax(date) : config.valueMax;
+    const valueText = isEmpty ? 'Empty' : (config.valueText?.(date) ?? `${valueNow}`);
     return {
         ...commonSegmentAttrs(props),
-        'aria-label': 'day,',
-        'aria-valuemin': valueMin,
+        'aria-label': config.label,
+        'aria-valuemin': config.valueMin,
         'aria-valuemax': valueMax,
         'aria-valuenow': valueNow,
         'aria-valuetext': valueText,
         'data-placeholder': isEmpty ? '' : undefined
     };
 }
+function daySegmentAttrs(props) {
+    return numericSegmentAttrs(props, {
+        field: 'day',
+        label: 'day,',
+        valueMin: 1,
+        valueMax: (date) => getDaysInMonth(date)
+    });
+}
 function monthSegmentAttrs(props) {
-    const { segmentValues, placeholder, formatter } = props;
-    const isEmpty = segmentValues.month === null;
-    const date = segmentValues.month ? placeholder.set({ month: segmentValues.month }) : placeholder;
-    const valueNow = date.month;
-    const valueMin = 1;
-    const valueMax = 12;
-    const valueText = isEmpty ? 'Empty' : `${valueNow} - ${formatter.fullMonth(toDate(date))}`;
-    return {
-        ...commonSegmentAttrs(props),
-        'aria-label': 'month, ',
-        contenteditable: true,
-        'aria-valuemin': valueMin,
-        'aria-valuemax': valueMax,
-        'aria-valuenow': valueNow,
-        'aria-valuetext': valueText,
-        'data-placeholder': isEmpty ? '' : undefined
-    };
+    return numericSegmentAttrs(props, {
+        field: 'month',
+        label: 'month, ',
+        valueMin: 1,
+        valueMax: 12,
+        valueText: (date) => `${date.month} - ${props.formatter.fullMonth(toDate(date))}`
+    });
 }
 function yearSegmentAttrs(props) {
-    const { segmentValues, placeholder } = props;
-    const isEmpty = segmentValues.year === null;
-    const date = segmentValues.year ? placeholder.set({ year: segmentValues.year }) : placeholder;
-    const valueMin = 1;
-    const valueMax = 9999;
-    const valueNow = date.year;
-    const valueText = isEmpty ? 'Empty' : `${valueNow}`;
-    return {
-        ...commonSegmentAttrs(props),
-        'aria-label': 'year, ',
-        'aria-valuemin': valueMin,
-        'aria-valuemax': valueMax,
-        'aria-valuenow': valueNow,
-        'aria-valuetext': valueText,
-        'data-placeholder': isEmpty ? '' : undefined
-    };
+    return numericSegmentAttrs(props, { field: 'year', label: 'year, ', valueMin: 1, valueMax: 9999 });
 }
 function hourSegmentAttrs(props) {
-    const { segmentValues, hourCycle, placeholder } = props;
-    if (!('hour' in segmentValues) || !('hour' in placeholder))
-        return {};
-    const isEmpty = segmentValues.hour === null;
-    const date = segmentValues.hour ? placeholder.set({ hour: segmentValues.hour }) : placeholder;
-    const valueMin = hourCycle === 12 ? 1 : 0;
-    const valueMax = hourCycle === 12 ? 12 : 23;
-    const valueNow = date.hour;
-    const valueText = isEmpty ? 'Empty' : `${valueNow} ${segmentValues.dayPeriod ?? ''}`;
-    return {
-        ...commonSegmentAttrs(props),
-        'aria-label': 'hour, ',
-        'aria-valuemin': valueMin,
-        'aria-valuemax': valueMax,
-        'aria-valuenow': valueNow,
-        'aria-valuetext': valueText,
-        'data-placeholder': isEmpty ? '' : undefined
-    };
+    const is12h = props.hourCycle === 12;
+    return numericSegmentAttrs(props, {
+        field: 'hour',
+        label: 'hour, ',
+        valueMin: is12h ? 1 : 0,
+        valueMax: is12h ? 12 : 23,
+        valueText: (date) => `${date.hour} ${props.segmentValues.dayPeriod ?? ''}`,
+        timePart: true
+    });
 }
 function minuteSegmentAttrs(props) {
-    const { segmentValues, placeholder } = props;
-    if (!('minute' in segmentValues) || !('minute' in placeholder))
-        return {};
-    const isEmpty = segmentValues.minute === null;
-    const date = segmentValues.minute ? placeholder.set({ minute: segmentValues.minute }) : placeholder;
-    const valueNow = date.minute;
-    const valueMin = 0;
-    const valueMax = 59;
-    const valueText = isEmpty ? 'Empty' : `${valueNow}`;
-    return {
-        ...commonSegmentAttrs(props),
-        'aria-label': 'minute, ',
-        'aria-valuemin': valueMin,
-        'aria-valuemax': valueMax,
-        'aria-valuenow': valueNow,
-        'aria-valuetext': valueText,
-        'data-placeholder': isEmpty ? '' : undefined
-    };
+    return numericSegmentAttrs(props, {
+        field: 'minute',
+        label: 'minute, ',
+        valueMin: 0,
+        valueMax: 59,
+        timePart: true
+    });
 }
 function secondSegmentAttrs(props) {
-    const { segmentValues, placeholder } = props;
-    if (!('second' in segmentValues) || !('second' in placeholder))
-        return {};
-    const isEmpty = segmentValues.second === null;
-    const date = segmentValues.second ? placeholder.set({ second: segmentValues.second }) : placeholder;
-    const valueNow = date.second;
-    const valueMin = 0;
-    const valueMax = 59;
-    const valueText = isEmpty ? 'Empty' : `${valueNow}`;
-    return {
-        ...commonSegmentAttrs(props),
-        'aria-label': 'second, ',
-        'aria-valuemin': valueMin,
-        'aria-valuemax': valueMax,
-        'aria-valuenow': valueNow,
-        'aria-valuetext': valueText,
-        'data-placeholder': isEmpty ? '' : undefined
-    };
+    return numericSegmentAttrs(props, {
+        field: 'second',
+        label: 'second, ',
+        valueMin: 0,
+        valueMax: 59,
+        timePart: true
+    });
 }
 function dayPeriodSegmentAttrs(props) {
     const { segmentValues } = props;
@@ -1188,7 +1204,7 @@ function dayPeriodSegmentAttrs(props) {
         return {};
     const valueMin = 0;
     const valueMax = 12;
-    const valueNow = segmentValues.hour ? (segmentValues.hour > 12 ? segmentValues.hour - 12 : segmentValues.hour) : 0;
+    const valueNow = segmentValues.hour != null ? (segmentValues.hour > 12 ? segmentValues.hour - 12 : segmentValues.hour) : 0;
     const valueText = segmentValues.dayPeriod ?? 'AM';
     return {
         ...commonSegmentAttrs(props),
@@ -1300,76 +1316,54 @@ function useDateField(props) {
                 .cycle(...cycleArgs)[part];
         return dateRef.set({ [part]: prevValue }).cycle(...cycleArgs)[part];
     }
-    function updateDayOrMonth(max, num, prev) {
+    /**
+     * Shared two-digit entry state machine for the numeric segments (day, month, hour,
+     * minute, second). Types one digit into `prev`, deciding the new value and whether focus
+     * should advance to the next segment.
+     *
+     * @param emptyZero  what a leading `0` produces on an empty segment — `0` for time parts
+     *                   (midnight/`:00` are valid), `null` for day/month (no zeroth day/month).
+     * @param moveOnOverflow  also advance focus when the two-digit total exceeds `max`
+     *                        (day/month behavior; time parts only advance on `num > maxStart`).
+     */
+    function updateNumberSegment(num, prev, max, { emptyZero = true, moveOnOverflow = false } = {}) {
         let moveToNext = false;
         const maxStart = Math.floor(max / 10);
-        /**
-         * If the user has left the segment, we want to reset the
-         * `prev` value so that we can start the segment over again
-         * when the user types a number.
-         */
+        // If the user has left the segment, reset `prev` so typing restarts the segment.
         if (props.hasLeftFocus()) {
             props.hasLeftFocus.set(false);
             prev = null;
         }
         if (prev === null) {
-            /**
-             * If the user types a 0 as the first number, we want
-             * to keep track of that so that when they type the next
-             * number, we can move to the next segment.
-             */
+            // A leading 0 is tracked so the next digit can advance to the next segment.
             if (num === 0) {
                 props.lastKeyZero.set(true);
-                return { value: null, moveToNext };
+                return { value: emptyZero ? 0 : null, moveToNext };
             }
-            /**
-             * If the last key was a 0, or if the first number is
-             * greater than the max start digit (0-3 in most cases), then
-             * we want to move to the next segment, since it's not possible
-             * to continue typing a valid number in this segment.
-             */
+            // If the last key was 0, or the first digit can't start a valid two-digit number
+            // (> the max start digit), advance to the next segment.
             if (props.lastKeyZero() || num > maxStart) {
-                // move to next
                 moveToNext = true;
             }
             props.lastKeyZero.set(false);
-            /**
-             * If none of the above conditions are met, then we can just
-             * return the number as the segment value and continue typing
-             * in this segment.
-             */
             return { value: num, moveToNext };
         }
-        /**
-         * If the number of digits is 2, or if the total with the existing digit
-         * and the pressed digit is greater than the maximum value for this
-         * month, then we will reset the segment as if the user had pressed the
-         * backspace key and then typed the number.
-         */
+        // Either the segment already holds two digits, or appending this digit overflows `max`:
+        // reset the segment as if backspaced and then typed.
         const digits = prev.toString().length;
         const total = Number.parseInt(prev.toString() + num.toString());
-        /**
-         * If the number of digits is 2, or if the total with the existing digit
-         * and the pressed digit is greater than the maximum value for this
-         * month, then we will reset the segment as if the user had pressed the
-         * backspace key and then typed the number.
-         */
         if (digits === 2 || total > max) {
-            /**
-             * As we're doing elsewhere, we're checking if the number is greater
-             * than the max start digit (0-3 in most months), and if so, we're
-             * going to move to the next segment.
-             */
-            if (num > maxStart || total > max) {
-                // move to next
+            if (num > maxStart || (moveOnOverflow && total > max)) {
                 moveToNext = true;
             }
             return { value: num, moveToNext };
         }
-        // move to next
         moveToNext = true;
         return { value: total, moveToNext };
     }
+    function updateDayOrMonth(max, num, prev) {
+        return updateNumberSegment(num, prev, max, { emptyZero: false, moveOnOverflow: true });
+    }
     function updateYear(num, prev) {
         let moveToNext = false;
         /**
@@ -1392,148 +1386,11 @@ function useDateField(props) {
         const int = Number.parseInt(str);
         return { value: int, moveToNext };
     }
-    function updateHour(num, prev) {
-        const max = 24;
-        let moveToNext = false;
-        const maxStart = Math.floor(max / 10);
-        /**
-         * If the user has left the segment, we want to reset the
-         * `prev` value so that we can start the segment over again
-         * when the user types a number.
-         */
-        // probably not implement, kind of weird
-        if (props.hasLeftFocus()) {
-            props.hasLeftFocus.set(false);
-            prev = null;
-        }
-        if (prev === null) {
-            /**
-             * If the user types a 0 as the first number, we want
-             * to keep track of that so that when they type the next
-             * number, we can move to the next segment.
-             */
-            if (num === 0) {
-                props.lastKeyZero.set(true);
-                return { value: 0, moveToNext };
-            }
-            /**
-             * If the last key was a 0, or if the first number is
-             * greater than the max start digit (0-3 in most cases), then
-             * we want to move to the next segment, since it's not possible
-             * to continue typing a valid number in this segment.
-             */
-            if (props.lastKeyZero() || num > maxStart) {
-                // move to next
-                moveToNext = true;
-            }
-            props.lastKeyZero.set(false);
-            /**
-             * If none of the above conditions are met, then we can just
-             * return the number as the segment value and continue typing
-             * in this segment.
-             */
-            return { value: num, moveToNext };
-        }
-        /**
-         * If the number of digits is 2, or if the total with the existing digit
-         * and the pressed digit is greater than the maximum value for this
-         * month, then we will reset the segment as if the user had pressed the
-         * backspace key and then typed the number.
-         */
-        const digits = prev.toString().length;
-        const total = Number.parseInt(prev.toString() + num.toString());
-        /**
-         * If the number of digits is 2, or if the total with the existing digit
-         * and the pressed digit is greater than the maximum value for this
-         * month, then we will reset the segment as if the user had pressed the
-         * backspace key and then typed the number.
-         */
-        if (digits === 2 || total > max) {
-            /**
-             * As we're doing elsewhere, we're checking if the number is greater
-             * than the max start digit (0-3 in most months), and if so, we're
-             * going to move to the next segment.
-             */
-            if (num > maxStart) {
-                // move to next
-                moveToNext = true;
-            }
-            return { value: num, moveToNext };
-        }
-        // move to next
-        moveToNext = true;
-        return { value: total, moveToNext };
+    function updateHour(num, prev, max) {
+        return updateNumberSegment(num, prev, max);
     }
     function updateMinuteOrSecond(num, prev) {
-        const max = 59;
-        let moveToNext = false;
-        const maxStart = Math.floor(max / 10);
-        /**
-         * If the user has left the segment, we want to reset the
-         * `prev` value so that we can start the segment over again
-         * when the user types a number.
-         */
-        if (props.hasLeftFocus()) {
-            props.hasLeftFocus.set(false);
-            prev = null;
-        }
-        if (prev === null) {
-            /**
-             * If the user types a 0 as the first number, we want
-             * to keep track of that so that when they type the next
-             * number, we can move to the next segment.
-             */
-            if (num === 0) {
-                props.lastKeyZero.set(true);
-                return { value: 0, moveToNext };
-            }
-            /**
-             * If the last key was a 0, or if the first number is
-             * greater than the max start digit (0-3 in most cases), then
-             * we want to move to the next segment, since it's not possible
-             * to continue typing a valid number in this segment.
-             */
-            if (props.lastKeyZero() || num > maxStart) {
-                // move to next
-                moveToNext = true;
-            }
-            props.lastKeyZero.set(false);
-            /**
-             * If none of the above conditions are met, then we can just
-             * return the number as the segment value and continue typing
-             * in this segment.
-             */
-            return { value: num, moveToNext };
-        }
-        /**
-         * If the number of digits is 2, or if the total with the existing digit
-         * and the pressed digit is greater than the maximum value for this
-         * month, then we will reset the segment as if the user had pressed the
-         * backspace key and then typed the number.
-         */
-        const digits = prev.toString().length;
-        const total = Number.parseInt(prev.toString() + num.toString());
-        /**
-         * If the number of digits is 2, or if the total with the existing digit
-         * and the pressed digit is greater than the maximum value for this
-         * month, then we will reset the segment as if the user had pressed the
-         * backspace key and then typed the number.
-         */
-        if (digits === 2 || total > max) {
-            /**
-             * As we're doing elsewhere, we're checking if the number is greater
-             * than the max start digit (0-3 in most months), and if so, we're
-             * going to move to the next segment.
-             */
-            if (num > maxStart) {
-                // move to next
-                moveToNext = true;
-            }
-            return { value: num, moveToNext };
-        }
-        // move to next
-        moveToNext = true;
-        return { value: total, moveToNext };
+        return updateNumberSegment(num, prev, 59);
     }
     function minuteSecondIncrementation({ e, part, dateRef, prevValue }) {
         const step = props.step()[part] ?? 1;
@@ -1661,22 +1518,24 @@ function useDateField(props) {
                     hourCycle
                 })
             }));
-            if ('dayPeriod' in props.segmentValues() && values.hour != null) {
-                if (values.hour < 12)
-                    props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'AM' }));
-                else if (values.hour)
-                    props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'PM' }));
+            // Keep the day period in sync with the (just-updated) 24-hour value.
+            const updatedHour = props.segmentValues().hour;
+            if ('dayPeriod' in props.segmentValues() && updatedHour != null) {
+                props.segmentValues.update((prev) => ({ ...prev, dayPeriod: dayPeriodForHour(updatedHour) }));
             }
             return;
         }
         if (isNumberString(e.key)) {
             const num = Number.parseInt(e.key);
-            const { value, moveToNext } = updateHour(num, prevValue);
-            if ('dayPeriod' in props.segmentValues() && value && value > 12)
-                props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'AM' }));
-            else if ('dayPeriod' in props.segmentValues() && value)
-                props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'PM' }));
-            props.segmentValues.update((prev) => ({ ...prev, hour: value }));
+            const is12h = hourCycle === 12;
+            const period = values.dayPeriod ?? 'AM';
+            // Run the two-digit entry machine in the user-visible clock space (1-12 in 12h
+            // mode, 0-23 otherwise), then store the canonical 24-hour value. The day period
+            // is owned by its own segment, so typing the hour must not flip it.
+            const prevDisplay = prevValue === null ? null : is12h ? to12Hour(prevValue) : prevValue;
+            const { value, moveToNext } = updateHour(num, prevDisplay, is12h ? 12 : 23);
+            const hour = value === null ? null : is12h ? to24Hour(value, period) : value;
+            props.segmentValues.update((prev) => ({ ...prev, hour }));
             if (moveToNext)
                 props.focusNext();
         }
@@ -1685,68 +1544,26 @@ function useDateField(props) {
             props.segmentValues.update((prev) => ({ ...prev, hour: deleteValue(prevValue) }));
         }
     }
-    function handleMinuteSegmentKeydown(e) {
-        const dateRef = props.placeholder();
-        const values = props.segmentValues();
-        if (!isAcceptableSegmentKey(e.key) ||
-            isSegmentNavigationKey(e.key) ||
-            !('minute' in dateRef) ||
-            !('minute' in values))
-            return;
-        const prevValue = values.minute;
-        if (e.key === ARROW_UP || e.key === ARROW_DOWN) {
-            props.segmentValues.update((prev) => ({
-                ...prev,
-                minute: minuteSecondIncrementation({
-                    e,
-                    part: 'minute',
-                    dateRef: props.placeholder(),
-                    prevValue
-                })
-            }));
-        }
-        if (isNumberString(e.key)) {
-            const num = Number.parseInt(e.key);
-            const { value, moveToNext } = updateMinuteOrSecond(num, prevValue);
-            props.segmentValues.update((prev) => ({ ...prev, minute: value }));
-            if (moveToNext)
-                props.focusNext();
-        }
-        if (e.key === BACKSPACE) {
-            props.hasLeftFocus.set(false);
-            props.segmentValues.update((prev) => ({ ...prev, minute: deleteValue(prevValue) }));
-        }
-    }
-    function handleSecondSegmentKeydown(e) {
+    // Minute and second segments behave identically; only the field differs.
+    function handleMinuteOrSecondSegmentKeydown(e, part) {
         const dateRef = props.placeholder();
         const values = props.segmentValues();
-        if (!isAcceptableSegmentKey(e.key) ||
-            isSegmentNavigationKey(e.key) ||
-            !('second' in dateRef) ||
-            !('second' in values))
+        if (!isAcceptableSegmentKey(e.key) || isSegmentNavigationKey(e.key) || !(part in dateRef) || !(part in values))
             return;
-        const prevValue = values.second;
+        const prevValue = values[part];
         if (e.key === ARROW_UP || e.key === ARROW_DOWN) {
-            props.segmentValues.update((prev) => ({
-                ...prev,
-                second: minuteSecondIncrementation({
-                    e,
-                    part: 'second',
-                    dateRef: props.placeholder(),
-                    prevValue
-                })
-            }));
+            const next = minuteSecondIncrementation({ e, part, dateRef: props.placeholder(), prevValue });
+            props.segmentValues.update((prev) => ({ ...prev, [part]: next }));
         }
         if (isNumberString(e.key)) {
-            const num = Number.parseInt(e.key);
-            const { value, moveToNext } = updateMinuteOrSecond(num, prevValue);
-            props.segmentValues.update((prev) => ({ ...prev, second: value }));
+            const { value, moveToNext } = updateMinuteOrSecond(Number.parseInt(e.key), prevValue);
+            props.segmentValues.update((prev) => ({ ...prev, [part]: value }));
             if (moveToNext)
                 props.focusNext();
         }
         if (e.key === BACKSPACE) {
             props.hasLeftFocus.set(false);
-            props.segmentValues.update((prev) => ({ ...prev, second: deleteValue(prevValue) }));
+            props.segmentValues.update((prev) => ({ ...prev, [part]: deleteValue(prevValue) }));
         }
     }
     function handleDayPeriodSegmentKeydown(e) {
@@ -1755,24 +1572,24 @@ function useDateField(props) {
             !('dayPeriod' in props.segmentValues()))
             return;
         const values = props.segmentValues();
-        if (e.key === ARROW_UP || e.key === ARROW_DOWN) {
-            if (values.dayPeriod === 'AM') {
-                props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'PM' }));
-                props.segmentValues.update((prev) => ({ ...prev, hour: values.hour + 12 }));
+        const setPeriod = (period) => {
+            if (values.dayPeriod === period)
                 return;
-            }
-            props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'AM' }));
-            props.segmentValues.update((prev) => ({ ...prev, hour: values.hour - 12 }));
+            // Re-anchor the canonical 24-hour value to the new period without ever leaving
+            // range; keep it null while the hour segment is still empty.
+            const hour = values.hour == null ? null : to24Hour(to12Hour(values.hour), period);
+            props.segmentValues.update((prev) => ({ ...prev, dayPeriod: period, hour }));
+        };
+        if (e.key === ARROW_UP || e.key === ARROW_DOWN) {
+            setPeriod(values.dayPeriod === 'AM' ? 'PM' : 'AM');
             return;
         }
-        if (['a', 'A'].includes(e.key) && values.dayPeriod !== 'AM') {
-            props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'AM' }));
-            props.segmentValues.update((prev) => ({ ...prev, hour: values.hour - 12 }));
+        if (['a', 'A'].includes(e.key)) {
+            setPeriod('AM');
             return;
         }
-        if (['p', 'P'].includes(e.key) && values.dayPeriod !== 'PM') {
-            props.segmentValues.update((prev) => ({ ...prev, dayPeriod: 'PM' }));
-            props.segmentValues.update((prev) => ({ ...prev, hour: values.hour + 12 }));
+        if (['p', 'P'].includes(e.key)) {
+            setPeriod('PM');
         }
     }
     function handleSegmentKeydown(e) {
@@ -1787,8 +1604,8 @@ function useDateField(props) {
             day: handleDaySegmentKeydown,
             year: handleYearSegmentKeydown,
             hour: handleHourSegmentKeydown,
-            minute: handleMinuteSegmentKeydown,
-            second: handleSecondSegmentKeydown,
+            minute: (e) => handleMinuteOrSecondSegmentKeydown(e, 'minute'),
+            second: (e) => handleMinuteOrSecondSegmentKeydown(e, 'second'),
             dayPeriod: handleDayPeriodSegmentKeydown,
             timeZoneName: () => { }
         };
@@ -1872,84 +1689,6 @@ function injectId(prefix) {
     return inject(RdxIdGenerator).getId(prefix);
 }
 
-/**
- * Announces messages to screen readers through an `aria-live` region, without moving focus.
- *
- * Own replacement for CDK's `LiveAnnouncer` — lazily appends a visually hidden live region to
- * the document body and writes messages into it. No-op on the server.
- */
-class RdxLiveAnnouncer {
-    constructor() {
-        this.document = inject(DOCUMENT);
-        this.isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
-        this.liveElement = null;
-        inject(DestroyRef).onDestroy(() => {
-            clearTimeout(this.previousTimeout);
-            this.liveElement?.remove();
-            this.liveElement = null;
-        });
-    }
-    /**
-     * Announces a message to screen readers.
-     *
-     * @param message The message to announce.
-     * @param politeness The politeness of the announcer element (defaults to `'polite'`).
-     * @param duration If provided, the message is cleared after this many milliseconds.
-     */
-    announce(message, politeness = 'polite', duration) {
-        if (!this.isBrowser) {
-            return;
-        }
-        const liveElement = this.getLiveElement();
-        clearTimeout(this.previousTimeout);
-        liveElement.setAttribute('aria-live', politeness);
-        // Clear the live element first, then set the message after a tick so that screen
-        // readers reliably pick up the change even when the text is identical.
-        liveElement.textContent = '';
-        this.previousTimeout = setTimeout(() => {
-            liveElement.textContent = message;
-            if (typeof duration === 'number') {
-                this.previousTimeout = setTimeout(() => (liveElement.textContent = ''), duration);
-            }
-        });
-    }
-    /** Clears the current announcement. */
-    clear() {
-        if (this.liveElement) {
-            this.liveElement.textContent = '';
-        }
-    }
-    getLiveElement() {
-        if (this.liveElement) {
-            return this.liveElement;
-        }
-        const element = this.document.createElement('div');
-        element.classList.add('rdx-live-announcer');
-        element.setAttribute('aria-atomic', 'true');
-        element.setAttribute('aria-live', 'polite');
-        // Visually hide the region while keeping it available to assistive technology.
-        element.style.position = 'absolute';
-        element.style.width = '1px';
-        element.style.height = '1px';
-        element.style.margin = '-1px';
-        element.style.padding = '0';
-        element.style.border = '0';
-        element.style.overflow = 'hidden';
-        element.style.clip = 'rect(0 0 0 0)';
-        element.style.clipPath = 'inset(100%)';
-        element.style.whiteSpace = 'nowrap';
-        this.document.body.appendChild(element);
-        this.liveElement = element;
-        return element;
-    }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RdxLiveAnnouncer, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RdxLiveAnnouncer, providedIn: 'root' }); }
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RdxLiveAnnouncer, decorators: [{
-            type: Injectable,
-            args: [{ providedIn: 'root' }]
-        }], ctorParameters: () => [] });
-
 /** Narrows to `null | undefined`. */
 function isNullish(value) {
     return value === null || value === undefined;
@@ -2028,6 +1767,127 @@ function equals(a, b, seen) {
     }
 }
 
+/**
+ * Converts an item value to the string shown to the user.
+ *
+ * Strings pass through unchanged; `null`/`undefined` become an empty string; everything else is
+ * coerced with `String()`. Primitives that hold object values (e.g. combobox) typically pass their
+ * own `itemToStringLabel` to render a field off the object instead.
+ */
+function itemToStringLabel(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (isNullish(value)) {
+        return '';
+    }
+    return String(value);
+}
+/**
+ * Converts an item value to the string used for form serialization. Defaults to the same rules as
+ * {@link itemToStringLabel}; kept as a separate export so a primitive can diverge label vs. value.
+ */
+function itemToStringValue(value) {
+    return itemToStringLabel(value);
+}
+/**
+ * Compares two item values for equality using an optional {@link ItemValueComparator}.
+ *
+ * @example
+ * isItemEqualToValue({ id: 1 }, { id: 1 }, 'id'); // true — compares the `id` key
+ * isItemEqualToValue({ id: 1 }, { id: 1 });       // true — deep equality fallback
+ */
+function isItemEqualToValue(a, b, comparator) {
+    if (typeof comparator === 'function') {
+        return comparator(a, b);
+    }
+    if (typeof comparator === 'string') {
+        if (isNullish(a) || isNullish(b)) {
+            return a === b;
+        }
+        return isEqual(a[comparator], b[comparator]);
+    }
+    return isEqual(a, b);
+}
+
+/**
+ * Announces messages to screen readers through an `aria-live` region, without moving focus.
+ *
+ * Own replacement for CDK's `LiveAnnouncer` — lazily appends a visually hidden live region to
+ * the document body and writes messages into it. No-op on the server.
+ */
+class RdxLiveAnnouncer {
+    constructor() {
+        this.document = inject(DOCUMENT);
+        this.isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
+        this.liveElement = null;
+        inject(DestroyRef).onDestroy(() => {
+            clearTimeout(this.previousTimeout);
+            this.liveElement?.remove();
+            this.liveElement = null;
+        });
+    }
+    /**
+     * Announces a message to screen readers.
+     *
+     * @param message The message to announce.
+     * @param politeness The politeness of the announcer element (defaults to `'polite'`).
+     * @param duration If provided, the message is cleared after this many milliseconds.
+     */
+    announce(message, politeness = 'polite', duration) {
+        if (!this.isBrowser) {
+            return;
+        }
+        const liveElement = this.getLiveElement();
+        clearTimeout(this.previousTimeout);
+        liveElement.setAttribute('aria-live', politeness);
+        // Clear the live element first, then set the message after a tick so that screen
+        // readers reliably pick up the change even when the text is identical.
+        liveElement.textContent = '';
+        this.previousTimeout = setTimeout(() => {
+            liveElement.textContent = message;
+            if (typeof duration === 'number') {
+                this.previousTimeout = setTimeout(() => (liveElement.textContent = ''), duration);
+            }
+        });
+    }
+    /** Clears the current announcement. */
+    clear() {
+        if (this.liveElement) {
+            this.liveElement.textContent = '';
+        }
+    }
+    getLiveElement() {
+        if (this.liveElement) {
+            return this.liveElement;
+        }
+        const element = this.document.createElement('div');
+        element.classList.add('rdx-live-announcer');
+        element.setAttribute('aria-atomic', 'true');
+        element.setAttribute('aria-live', 'polite');
+        // Visually hide the region while keeping it available to assistive technology.
+        element.style.position = 'absolute';
+        element.style.width = '1px';
+        element.style.height = '1px';
+        element.style.margin = '-1px';
+        element.style.padding = '0';
+        element.style.border = '0';
+        element.style.overflow = 'hidden';
+        element.style.clip = 'rect(0 0 0 0)';
+        element.style.clipPath = 'inset(100%)';
+        element.style.whiteSpace = 'nowrap';
+        this.document.body.appendChild(element);
+        this.liveElement = element;
+        return element;
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RdxLiveAnnouncer, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RdxLiveAnnouncer, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RdxLiveAnnouncer, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }], ctorParameters: () => [] });
+
 /**
  * Creates an Angular provider that binds the given token to the existing instance
  * of the specified class. This is especially useful when you want multiple
@@ -2123,18 +1983,24 @@ function resizeEffect(options) {
 }
 
 /**
- * Process-wide ownership of `document.body`'s overflow while one or more overlays lock scrolling.
+ * Process-wide ownership of the document scroller's overflow while one or more overlays lock
+ * scrolling.
  *
  * A single shared counter across every primitive that locks scroll is essential: with separate
  * per-primitive counters, a popover and a dialog open at the same time would each capture the
- * other's already-locked `overflow: hidden` as the "original" value and restore it on close,
- * leaving the page permanently unscrollable.
+ * other's already-locked state as the "original" and restore it on close, leaving the page
+ * permanently unscrollable.
  */
-let originalBodyOverflow = null;
+let original = null;
 let scrollLockCount = 0;
 /**
- * Locks `document.body` scrolling while `active()` is `true`, and restores the original overflow
- * when it becomes `false` or the calling context is destroyed.
+ * Locks page scrolling while `active()` is `true`, and restores the original state when it becomes
+ * `false` or the calling context is destroyed.
+ *
+ * Locks **both** `<body>` and `<html>`: a `body { overflow: hidden }` lock alone does *not* stop the
+ * page when `<html>` is the scroller (e.g. a global `overflow-y: scroll`, as Storybook sets), because
+ * body-overflow only propagates to the viewport when `<html>`'s overflow is `visible`. The width of
+ * the removed scrollbar is added as `padding-right` on `<html>` so the page doesn't shift.
  *
  * Lock ownership is shared across all callers via a single module-level counter, so nested or
  * concurrent overlays compose correctly. Must be called in an injection context.
@@ -2146,10 +2012,22 @@ function useScrollLock(active) {
         if (isLocked) {
             return;
         }
-        const body = document.body;
         if (scrollLockCount === 0) {
-            originalBodyOverflow = body.style.overflow;
+            const html = document.documentElement;
+            const body = document.body;
+            const win = document.defaultView;
+            const scrollbarWidth = win ? Math.max(0, win.innerWidth - html.clientWidth) : 0;
+            original = {
+                bodyOverflow: body.style.overflow,
+                htmlOverflow: html.style.overflow,
+                htmlPaddingRight: html.style.paddingRight
+            };
             body.style.overflow = 'hidden';
+            html.style.overflow = 'hidden';
+            if (scrollbarWidth > 0) {
+                const currentPadding = win ? parseFloat(win.getComputedStyle(html).paddingRight) || 0 : 0;
+                html.style.paddingRight = `${currentPadding + scrollbarWidth}px`;
+            }
         }
         scrollLockCount++;
         isLocked = true;
@@ -2160,9 +2038,12 @@ function useScrollLock(active) {
         }
         scrollLockCount--;
         isLocked = false;
-        if (scrollLockCount === 0 && originalBodyOverflow !== null) {
-            document.body.style.overflow = originalBodyOverflow;
-            originalBodyOverflow = null;
+        if (scrollLockCount === 0 && original !== null) {
+            const html = document.documentElement;
+            document.body.style.overflow = original.bodyOverflow;
+            html.style.overflow = original.htmlOverflow;
+            html.style.paddingRight = original.htmlPaddingRight;
+            original = null;
         }
     };
     effect(() => {
@@ -2260,6 +2141,56 @@ function findNextFocusableElement(elements, currentElement, options, iterations
     return candidate;
 }
 
+/**
+ * Creates locale-aware `contains` / `startsWith` / `endsWith` predicates.
+ *
+ * Matching uses `Intl.Collator` with `sensitivity: 'base'` and `usage: 'search'` by default, so
+ * comparisons ignore case and diacritics. An empty (or whitespace-only) `query` matches everything,
+ * which is the natural "no filter applied" state for a combobox.
+ *
+ * @example
+ * const { contains } = useFilter();
+ * contains('Äpfel', 'ap'); // true
+ */
+function useFilter(options) {
+    const { locale, ...collatorOptions } = options ?? {};
+    const collator = new Intl.Collator(locale, {
+        usage: 'search',
+        sensitivity: 'base',
+        ...collatorOptions
+    });
+    // `Intl.Collator` only compares whole strings, so we scan every substring window of `text`
+    // the same length as `query` and treat a collator match as a hit. This keeps the locale rules
+    // (case/diacritic folding) consistent with `===`-style equality the collator provides.
+    const matchesAt = (text, query, start) => collator.compare(text.slice(start, start + query.length), query) === 0;
+    const isEmpty = (query) => query.length === 0;
+    return {
+        contains(text, query) {
+            if (isEmpty(query)) {
+                return true;
+            }
+            for (let i = 0; i + query.length <= text.length; i++) {
+                if (matchesAt(text, query, i)) {
+                    return true;
+                }
+            }
+            return false;
+        },
+        startsWith(text, query) {
+            if (isEmpty(query)) {
+                return true;
+            }
+            return query.length <= text.length && matchesAt(text, query, 0);
+        },
+        endsWith(text, query) {
+            if (isEmpty(query)) {
+                return true;
+            }
+            return query.length <= text.length && matchesAt(text, query, text.length - query.length);
+        }
+    };
+}
+
 const graceAreaContainers = new WeakMap();
 function createSignalEvent() {
     const handlers = new Set();
@@ -2472,6 +2403,86 @@ function getHullPresorted(points) {
     return upper.concat(lower);
 }
 
+/**
+ * Highlight-model list navigation over a set of items, decoupled from DOM focus.
+ *
+ * Unlike roving `tabindex`, the highlight is pure state: callers move it with the keyboard while DOM
+ * focus stays on a single controlling element (e.g. a combobox `<input>`), which exposes
+ * {@link ListHighlight.activeId} as `aria-activedescendant`. Navigation only ever lands on items for
+ * which `isNavigable` returns `true`, so hidden (filtered-out) and disabled items are skipped. A
+ * self-healing effect clears the highlight if its item stops being navigable or leaves the list, so
+ * `activeId` never references a detached or hidden element.
+ *
+ * Must be called in an injection context, or given an `injector`.
+ */
+function useListHighlight(options) {
+    const { items, isNavigable, getId, loop, injector } = options;
+    const highlighted = signal(null, ...(ngDevMode ? [{ debugName: "highlighted" }] : /* istanbul ignore next */ []));
+    const navigable = computed(() => items().filter((item) => isNavigable(item)), ...(ngDevMode ? [{ debugName: "navigable" }] : /* istanbul ignore next */ []));
+    const activeId = computed(() => {
+        const item = highlighted();
+        return item === null ? undefined : getId(item);
+    }, ...(ngDevMode ? [{ debugName: "activeId" }] : /* istanbul ignore next */ []));
+    const setIfNavigable = (item) => {
+        if (item === null || isNavigable(item)) {
+            highlighted.set(item);
+        }
+    };
+    const step = (direction) => {
+        const list = navigable();
+        if (list.length === 0) {
+            highlighted.set(null);
+            return;
+        }
+        const current = highlighted();
+        const currentIndex = current === null ? -1 : list.indexOf(current);
+        // No valid anchor → enter from the appropriate end.
+        if (currentIndex === -1) {
+            highlighted.set(direction === 1 ? list[0] : list[list.length - 1]);
+            return;
+        }
+        let nextIndex = currentIndex + direction;
+        const shouldLoop = loop ? loop() : true;
+        if (nextIndex < 0) {
+            nextIndex = shouldLoop ? list.length - 1 : 0;
+        }
+        else if (nextIndex >= list.length) {
+            nextIndex = shouldLoop ? 0 : list.length - 1;
+        }
+        highlighted.set(list[nextIndex]);
+    };
+    // Self-heal: drop a highlight that is no longer navigable (filtered out, disabled, destroyed).
+    effect(() => {
+        const list = navigable();
+        const current = untracked(highlighted);
+        if (current !== null && !list.includes(current)) {
+            highlighted.set(null);
+        }
+    }, injector ? { injector } : undefined);
+    return {
+        highlightedItem: highlighted.asReadonly(),
+        activeId,
+        first() {
+            const list = navigable();
+            highlighted.set(list.length > 0 ? list[0] : null);
+        },
+        last() {
+            const list = navigable();
+            highlighted.set(list.length > 0 ? list[list.length - 1] : null);
+        },
+        next() {
+            step(1);
+        },
+        previous() {
+            step(-1);
+        },
+        set: setIfNavigable,
+        clear() {
+            highlighted.set(null);
+        }
+    };
+}
+
 /** Pointer travel (px) before a press becomes a drag — below this a press stays a click/tap. */
 const DRAG_THRESHOLD = 4;
 /**
@@ -2760,5 +2771,5 @@ var RdxPositionAlign;
  * Generated bundle index. Do not edit.
  */
 
-export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RdxControlValueAccessor, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, SHIFT, SPACE, SPACE_CODE, TAB, a, areAllDaysBetweenValid, clamp, createContent, createContext, createFormatter, createMonth, createMonths, elementSize, getActiveElement, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getMaxTransitionDuration, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectId, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isNullish, isNumberString, isSegmentNavigationKey, isZonedDateTime, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideToken, provideValueAccessor, resizeEffect, roundToStepPrecision, segmentBuilders, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useArrowNavigation, useDateField, useGraceArea, usePointerDrag, useScrollLock, useTransitionStatus, watch };
+export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RdxControlValueAccessor, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, SHIFT, SPACE, SPACE_CODE, TAB, TIME_GRANULARITIES, a, areAllDaysBetweenValid, clamp, createContent, createContext, createFormatter, createMonth, createMonths, elementSize, getActiveElement, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getMaxTransitionDuration, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectId, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isItemEqualToValue, isNullish, isNumberString, isSegmentNavigationKey, isZonedDateTime, itemToStringLabel, itemToStringValue, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideToken, provideValueAccessor, resizeEffect, roundToStepPrecision, segmentBuilders, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useArrowNavigation, useDateField, useFilter, useGraceArea, useListHighlight, usePointerDrag, useScrollLock, useTransitionStatus, watch };
 //# sourceMappingURL=radix-ng-primitives-core.mjs.map