ngx-mq 2.11.3 → 3.1.0

package/fesm2022/ngx-mq.mjs

@@ -1,5 +1,4 @@
-import { InjectionToken, inject, isDevMode, signal, DestroyRef, assertInInjectionContext } from '@angular/core';
-import { createComputed, SIGNAL } from '@angular/core/primitives/signals';
+import { InjectionToken, inject, isDevMode, signal, DestroyRef, computed, assertInInjectionContext } from '@angular/core';
 
 const TAILWIND_BREAKPOINTS = {
     sm: 640,
@@ -23,11 +22,29 @@ const MATERIAL_BREAKPOINTS = {
 };
 const DEFAULT_BREAKPOINT_EPSILON = 0.02;
 
+/**
+ * Holds the active {@link MqBreakpoints} map. Has no default: configure it with
+ * {@link provideBreakpoints} or a preset. Inject it to read breakpoints directly.
+ *
+ * @category Injection Tokens
+ */
 const MQ_BREAKPOINTS = new InjectionToken('MQ_BREAKPOINTS');
+/**
+ * Holds the epsilon used for exclusive upper bounds. Set it with
+ * {@link provideBreakpointEpsilon}; defaults to `0.02`.
+ *
+ * @category Injection Tokens
+ */
 const MQ_BREAKPOINT_EPSILON = new InjectionToken('MQ_BREAKPOINT_EPSILON', {
     providedIn: 'root',
     factory: () => DEFAULT_BREAKPOINT_EPSILON,
 });
+/**
+ * Holds the value query signals report during SSR. Set it with
+ * {@link provideSsrValue}; defaults to `false`.
+ *
+ * @category Injection Tokens
+ */
 const NGX_MQ_SSR_VALUE = new InjectionToken('NGX_MQ_SSR_VALUE', {
     providedIn: 'root',
     factory: () => false,
@@ -54,18 +71,22 @@ function resolveBreakpoint(bp) {
     const breakpoints = assertBreakpointsProvided();
     return assertBreakpointExists(bp.trim(), breakpoints);
 }
+function validateBreakpointValue(key, value) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`[ngx-mq] Breakpoint "${key}" must be a finite number, got ${value}.`);
+    }
+    if (value <= 0) {
+        throw new Error(`[ngx-mq] Breakpoint "${key}" must be > 0, got ${value}.`);
+    }
+}
 function normalizeBreakpoints(bps) {
     const out = {};
     for (const [rawKey, value] of Object.entries(bps)) {
         const key = rawKey.trim();
-        if (isDevMode()) {
-            if (!Number.isFinite(value)) {
-                throw new Error(`[ngx-mq] Breakpoint "${key}" must be a finite number, got ${value}.`);
-            }
-            if (value <= 0) {
-                throw new Error(`[ngx-mq] Breakpoint "${key}" must be > 0, got ${value}.`);
-            }
-        }
+        // Dev-only guard; the false branch never runs in production builds.
+        /* v8 ignore next */
+        if (isDevMode())
+            validateBreakpointValue(key, value);
         out[key] = value;
     }
     return Object.freeze(out);
@@ -167,11 +188,7 @@ function createConsumer(query, options) {
     const defaultSsrValue = inject(NGX_MQ_SSR_VALUE);
     const effectiveSsrValue = options?.ssrValue ?? defaultSsrValue;
     const querySignal = retainUntilDestroy(query, effectiveSsrValue);
-    const getter = createComputed(() => querySignal());
-    if (isDevMode()) {
-        getter[SIGNAL].debugName = options?.debugName;
-    }
-    return getter;
+    return computed(() => querySignal(), { debugName: options?.debugName });
 }
 function createConsumerLabel(descriptor) {
     return `[NgxMq Signal: ${descriptor}]`;
@@ -181,6 +198,29 @@ function normalizeQuery(value) {
     return value.trim().replace(/\s+/g, ' ').toLowerCase();
 }
 
+/**
+ * Tracks whether the viewport width is **at or above** a breakpoint.
+ *
+ * Builds a `(min-width: <bp>px)` query from the value registered for `bp` via
+ * {@link provideBreakpoints} (or a preset like {@link provideTailwindBreakpoints}).
+ *
+ * @param bp - Name of a configured breakpoint, e.g. `'md'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the viewport width is `>=` the breakpoint.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * export class LayoutComponent {
+ *   readonly isDesktop = up('lg');
+ * }
+ * ```
+ *
+ * @see {@link down} and {@link between} for the complementary ranges.
+ * @category Breakpoints
+ */
 function up(bp, options) {
     isDevMode() && assertInInjectionContext(up);
     const query = normalizeQuery(`(min-width: ${resolveBreakpoint(bp)}px)`);
@@ -188,6 +228,29 @@ function up(bp, options) {
     consumer.toString = () => createConsumerLabel(`up(${bp})`);
     return consumer;
 }
+/**
+ * Tracks whether the viewport width is **below** a breakpoint.
+ *
+ * Builds a `(max-width: <bp - epsilon>px)` query. The upper bound is **exclusive**:
+ * a small epsilon is subtracted so `down('md')` and {@link up}`('md')` never overlap.
+ *
+ * @param bp - Name of a configured breakpoint, e.g. `'md'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the viewport width is `<` the breakpoint.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * export class NavComponent {
+ *   readonly isMobile = down('md');
+ * }
+ * ```
+ *
+ * @see {@link provideBreakpointEpsilon} to tune the exclusive-bound epsilon.
+ * @category Breakpoints
+ */
 function down(bp, options) {
     isDevMode() && assertInInjectionContext(down);
     const query = normalizeQuery(`(max-width: ${applyMaxEpsilon(resolveBreakpoint(bp))}px)`);
@@ -195,6 +258,29 @@ function down(bp, options) {
     consumer.toString = () => createConsumerLabel(`down(${bp})`);
     return consumer;
 }
+/**
+ * Tracks whether the viewport width falls within the range `[minBp, maxBp)`.
+ *
+ * Combines `min-width` and `max-width` into a single query. The lower bound is
+ * inclusive and the upper bound is **exclusive** (epsilon is subtracted from `maxBp`).
+ *
+ * @param minBp - Name of the lower (inclusive) breakpoint.
+ * @param maxBp - Name of the upper (exclusive) breakpoint.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the width is in `[minBp, maxBp)`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * export class GridComponent {
+ *   readonly isTablet = between('md', 'lg');
+ * }
+ * ```
+ *
+ * @category Breakpoints
+ */
 function between(minBp, maxBp, options) {
     isDevMode() && assertInInjectionContext(between);
     const minPx = resolveBreakpoint(minBp);
@@ -204,6 +290,24 @@ function between(minBp, maxBp, options) {
     consumer.toString = () => createConsumerLabel(`between(${minBp}, ${maxBp})`);
     return consumer;
 }
+/**
+ * Tracks the screen orientation via the `(orientation: ...)` media feature.
+ *
+ * @param value - `'portrait'` (height `>=` width) or `'landscape'` (width `>` height).
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the orientation matches `value`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly isLandscape = orientation('landscape');
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/orientation | MDN: orientation}
+ * @category Media Features
+ */
 function orientation(value, options) {
     isDevMode() && assertInInjectionContext(orientation);
     const query = normalizeQuery(`(orientation: ${value})`);
@@ -211,6 +315,24 @@ function orientation(value, options) {
     consumer.toString = () => createConsumerLabel(`orientation(${value})`);
     return consumer;
 }
+/**
+ * Tracks the user's preferred color scheme via `(prefers-color-scheme: ...)`.
+ *
+ * @param value - `'light'` or `'dark'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the system scheme matches `value`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly isDark = colorScheme('dark');
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme | MDN: prefers-color-scheme}
+ * @category Media Features
+ */
 function colorScheme(value, options) {
     isDevMode() && assertInInjectionContext(colorScheme);
     const query = normalizeQuery(`(prefers-color-scheme: ${value})`);
@@ -218,6 +340,25 @@ function colorScheme(value, options) {
     consumer.toString = () => createConsumerLabel(`colorScheme(${value})`);
     return consumer;
 }
+/**
+ * Tracks how the app is being displayed via the `(display-mode: ...)` feature,
+ * useful for detecting installed PWAs.
+ *
+ * @param value - One of {@link DisplayModeOption}, e.g. `'standalone'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the display mode matches `value`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly isInstalledPwa = displayMode('standalone');
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/display-mode | MDN: display-mode}
+ * @category Media Features
+ */
 function displayMode(value, options) {
     isDevMode() && assertInInjectionContext(displayMode);
     const query = normalizeQuery(`(display-mode: ${value})`);
@@ -225,6 +366,24 @@ function displayMode(value, options) {
     consumer.toString = () => createConsumerLabel(`displayMode(${value})`);
     return consumer;
 }
+/**
+ * Tracks whether the user has requested reduced motion via
+ * `(prefers-reduced-motion: reduce)`.
+ *
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while reduced motion is preferred.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly reduceMotion = reducedMotion();
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion | MDN: prefers-reduced-motion}
+ * @category Media Features
+ */
 function reducedMotion(options) {
     isDevMode() && assertInInjectionContext(reducedMotion);
     const query = normalizeQuery('(prefers-reduced-motion: reduce)');
@@ -232,6 +391,49 @@ function reducedMotion(options) {
     consumer.toString = () => createConsumerLabel('reducedMotion');
     return consumer;
 }
+/**
+ * Tracks the user's contrast preference via `(prefers-contrast: ...)`.
+ *
+ * @param value - `'more'`, `'less'`, `'no-preference'`, or `'custom'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the contrast preference matches `value`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly wantsMoreContrast = prefersContrast('more');
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast | MDN: prefers-contrast}
+ * @category Media Features
+ */
+function prefersContrast(value, options) {
+    isDevMode() && assertInInjectionContext(prefersContrast);
+    const query = normalizeQuery(`(prefers-contrast: ${value})`);
+    const consumer = createConsumer(query, options);
+    consumer.toString = () => createConsumerLabel(`prefersContrast(${value})`);
+    return consumer;
+}
+/**
+ * Tracks whether the **primary** input device can hover via `(hover: hover)`.
+ *
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the primary pointer supports hover.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly canHover = hover();
+ * ```
+ *
+ * @see {@link anyHover} to test **any** available input device.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/hover | MDN: hover}
+ * @category Media Features
+ */
 function hover(options) {
     isDevMode() && assertInInjectionContext(hover);
     const query = normalizeQuery('(hover: hover)');
@@ -239,6 +441,24 @@ function hover(options) {
     consumer.toString = () => createConsumerLabel('hover');
     return consumer;
 }
+/**
+ * Tracks whether **any** available input device can hover via `(any-hover: hover)`.
+ *
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while at least one pointer supports hover.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly anyCanHover = anyHover();
+ * ```
+ *
+ * @see {@link hover} to test only the primary input device.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/any-hover | MDN: any-hover}
+ * @category Media Features
+ */
 function anyHover(options) {
     isDevMode() && assertInInjectionContext(anyHover);
     const query = normalizeQuery('(any-hover: hover)');
@@ -246,6 +466,25 @@ function anyHover(options) {
     consumer.toString = () => createConsumerLabel('anyHover');
     return consumer;
 }
+/**
+ * Tracks the accuracy of the **primary** pointer via `(pointer: ...)`.
+ *
+ * @param value - `'fine'` (mouse/stylus), `'coarse'` (touch), or `'none'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the primary pointer matches `value`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly isTouch = pointer('coarse');
+ * ```
+ *
+ * @see {@link anyPointer} to test **any** available input device.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pointer | MDN: pointer}
+ * @category Media Features
+ */
 function pointer(value, options) {
     isDevMode() && assertInInjectionContext(pointer);
     const query = normalizeQuery(`(pointer: ${value})`);
@@ -253,6 +492,25 @@ function pointer(value, options) {
     consumer.toString = () => createConsumerLabel(`pointer(${value})`);
     return consumer;
 }
+/**
+ * Tracks the accuracy of **any** available pointer via `(any-pointer: ...)`.
+ *
+ * @param value - `'fine'` (mouse/stylus), `'coarse'` (touch), or `'none'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while at least one pointer matches `value`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly hasFinePointer = anyPointer('fine');
+ * ```
+ *
+ * @see {@link pointer} to test only the primary input device.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/any-pointer | MDN: any-pointer}
+ * @category Media Features
+ */
 function anyPointer(value, options) {
     isDevMode() && assertInInjectionContext(anyPointer);
     const query = normalizeQuery(`(any-pointer: ${value})`);
@@ -260,6 +518,24 @@ function anyPointer(value, options) {
     consumer.toString = () => createConsumerLabel(`anyPointer(${value})`);
     return consumer;
 }
+/**
+ * Tracks the approximate color gamut of the display via `(color-gamut: ...)`.
+ *
+ * @param value - `'srgb'`, `'p3'`, or `'rec2020'` (ordered by increasing range).
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that is `true` while the display covers `value`.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly isWideGamut = colorGamut('p3');
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@media/color-gamut | MDN: color-gamut}
+ * @category Media Features
+ */
 function colorGamut(value, options) {
     isDevMode() && assertInInjectionContext(colorGamut);
     const query = normalizeQuery(`(color-gamut: ${value})`);
@@ -267,6 +543,27 @@ function colorGamut(value, options) {
     consumer.toString = () => createConsumerLabel(`colorGamut(${value})`);
     return consumer;
 }
+/**
+ * Tracks an arbitrary, raw CSS media query.
+ *
+ * Use this escape hatch for any feature not covered by the dedicated helpers.
+ * The query is normalized (trimmed, collapsed whitespace, lower-cased) before use.
+ *
+ * @param query - A valid CSS media query, e.g. `'(min-resolution: 2dppx)'`.
+ * @param options - Optional per-call settings ({@link CreateMediaQueryOptions}).
+ * @returns A `Signal<boolean>` that reflects the live result of the query.
+ *
+ * @remarks Must be called within an Angular
+ * [injection context](https://angular.dev/guide/di/dependency-injection-context).
+ *
+ * @example
+ * ```ts
+ * readonly isRetina = matchMediaSignal('(min-resolution: 2dppx)');
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries | MDN: CSS media queries}
+ * @category Custom Queries
+ */
 function matchMediaSignal(query, options) {
     isDevMode() && assertInInjectionContext(matchMediaSignal);
     const media = normalizeQuery(query);
@@ -275,30 +572,182 @@ function matchMediaSignal(query, options) {
     return consumer;
 }
 
+const LABEL_RE = /^\[NgxMq Signal: (.+)]$/;
+/** Extracts the inner descriptor from an ngx-mq signal label, or falls back to its raw toString(). */
+function describe(condition) {
+    const raw = condition.toString();
+    const match = LABEL_RE.exec(raw);
+    return match ? match[1] : raw;
+}
+/**
+ * Combines boolean signals with logical **AND**.
+ *
+ * Composition happens at the signal level, so the underlying media-query
+ * listeners stay shared and are still cleaned up automatically.
+ *
+ * @param conditions - Boolean signals to combine. An empty call returns a
+ * signal that is always `true` (vacuous truth).
+ * @returns A `Signal<boolean>` that is `true` only when **every** condition is `true`.
+ *
+ * @example
+ * ```ts
+ * readonly isLandscapeDesktop = and(up('lg'), orientation('landscape'), hover());
+ * ```
+ *
+ * @see {@link or} and {@link not}.
+ * @category Combining Signals
+ */
+function and(...conditions) {
+    const result = computed(() => conditions.every((condition) => condition()), ...(ngDevMode ? [{ debugName: "result" }] : []));
+    result.toString = () => createConsumerLabel(`and(${conditions.map(describe).join(', ')})`);
+    return result;
+}
+/**
+ * Combines boolean signals with logical **OR**.
+ *
+ * Composition happens at the signal level, so the underlying media-query
+ * listeners stay shared and are still cleaned up automatically.
+ *
+ * @param conditions - Boolean signals to combine. An empty call returns a
+ * signal that is always `false`.
+ * @returns A `Signal<boolean>` that is `true` when **at least one** condition is `true`.
+ *
+ * @example
+ * ```ts
+ * readonly prefersSimpleUi = or(down('md'), reducedMotion());
+ * ```
+ *
+ * @see {@link and} and {@link not}.
+ * @category Combining Signals
+ */
+function or(...conditions) {
+    const result = computed(() => conditions.some((condition) => condition()), ...(ngDevMode ? [{ debugName: "result" }] : []));
+    result.toString = () => createConsumerLabel(`or(${conditions.map(describe).join(', ')})`);
+    return result;
+}
+/**
+ * Negates a boolean signal.
+ *
+ * Useful for features that have no direct inverse helper, such as
+ * "devices without hover": `not(hover())`.
+ *
+ * @param condition - The boolean signal to invert.
+ * @returns A `Signal<boolean>` that is `true` when `condition` is `false`, and vice versa.
+ *
+ * @example
+ * ```ts
+ * readonly isTouchLike = not(hover());
+ * ```
+ *
+ * @see {@link and} and {@link or}.
+ * @category Combining Signals
+ */
+function not(condition) {
+    const result = computed(() => !condition(), ...(ngDevMode ? [{ debugName: "result" }] : []));
+    result.toString = () => createConsumerLabel(`not(${describe(condition)})`);
+    return result;
+}
+
+/**
+ * Registers a custom breakpoint map, enabling {@link up}, {@link down} and {@link between}.
+ *
+ * Provide once at bootstrap, or at any injector level to scope/override breakpoints.
+ *
+ * @param bps - A {@link MqBreakpoints} map of names to minimum widths in pixels.
+ * @returns An Angular {@link Provider}.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideBreakpoints({ sm: 640, md: 768, lg: 1024 })],
+ * });
+ * ```
+ *
+ * @category Providers
+ */
 function provideBreakpoints(bps) {
     return { provide: MQ_BREAKPOINTS, useValue: normalizeBreakpoints(bps) };
 }
+/**
+ * Registers the default Tailwind CSS breakpoints:
+ * `sm: 640, md: 768, lg: 1024, xl: 1280, 2xl: 1536`.
+ *
+ * @returns An Angular {@link Provider}.
+ * @category Providers
+ */
 function provideTailwindBreakpoints() {
     return provideBreakpoints(TAILWIND_BREAKPOINTS);
 }
+/**
+ * Registers the default Bootstrap breakpoints:
+ * `sm: 576, md: 768, lg: 992, xl: 1200, xxl: 1400`.
+ *
+ * @returns An Angular {@link Provider}.
+ * @category Providers
+ */
 function provideBootstrapBreakpoints() {
     return provideBreakpoints(BOOTSTRAP_BREAKPOINTS);
 }
+/**
+ * Registers the default Material 2 breakpoints:
+ * `sm: 600, md: 905, lg: 1240, xl: 1440`.
+ *
+ * @returns An Angular {@link Provider}.
+ * @category Providers
+ */
 function provideMaterialBreakpoints() {
     return provideBreakpoints(MATERIAL_BREAKPOINTS);
 }
+/**
+ * Sets the epsilon subtracted from exclusive upper bounds in {@link down} and
+ * {@link between}, preventing adjacent ranges from overlapping.
+ *
+ * @param epsilon - A value in the range `(0, 1]`. Defaults to `0.02`.
+ * @returns An Angular {@link Provider}.
+ *
+ * @example
+ * ```ts
+ * provideBreakpointEpsilon(0.02);
+ * ```
+ *
+ * @category Providers
+ */
 function provideBreakpointEpsilon(epsilon = DEFAULT_BREAKPOINT_EPSILON) {
+    // Dev-only guard; the false branch never runs in production builds.
+    /* v8 ignore next */
     if (isDevMode())
         validateEpsilon(epsilon);
     return { provide: MQ_BREAKPOINT_EPSILON, useValue: epsilon };
 }
+/**
+ * Sets the app-wide value query signals report during server-side rendering,
+ * where `matchMedia` is unavailable. A per-call `ssrValue` overrides this.
+ *
+ * @param value - The boolean returned by every signal on the server.
+ * @returns An Angular {@link Provider}.
+ *
+ * @example
+ * ```ts
+ * provideSsrValue(true);
+ * ```
+ *
+ * @category Providers
+ */
 function provideSsrValue(value) {
     return { provide: NGX_MQ_SSR_VALUE, useValue: value };
 }
 
+/**
+ * @packageDocumentation
+ *
+ * @document ../guides/getting-started.md
+ * @document ../guides/ssr.md
+ * @document ../guides/recipes.md
+ */
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { MQ_BREAKPOINTS, MQ_BREAKPOINT_EPSILON, NGX_MQ_SSR_VALUE, anyHover, anyPointer, between, colorGamut, colorScheme, displayMode, down, hover, matchMediaSignal, orientation, pointer, provideBootstrapBreakpoints, provideBreakpointEpsilon, provideBreakpoints, provideMaterialBreakpoints, provideSsrValue, provideTailwindBreakpoints, reducedMotion, up };
+export { MQ_BREAKPOINTS, MQ_BREAKPOINT_EPSILON, NGX_MQ_SSR_VALUE, and, anyHover, anyPointer, between, colorGamut, colorScheme, displayMode, down, hover, matchMediaSignal, not, or, orientation, pointer, prefersContrast, provideBootstrapBreakpoints, provideBreakpointEpsilon, provideBreakpoints, provideMaterialBreakpoints, provideSsrValue, provideTailwindBreakpoints, reducedMotion, up };
 //# sourceMappingURL=ngx-mq.mjs.map