react-responsive-tools 2.6.0 → 2.6.1

package/README.MD

@@ -8,10 +8,6 @@ The package is based on [react-responsive](https://www.npmjs.com/package/react-r
 
 To install the project, run the following command:
 
-### Установка
-
-Пожалуйста, убедитесь, что вы установили следующие зависимости:
-
 ```sh
 yarn add react-responsive
 ```
@@ -58,6 +54,16 @@ This command will run the `reinit.sh` script, which will recreate the necessary
 
 The following horizontal and vertical breakpoints are provided by default:
 
+### Preferred Adaptive Variant (`PREFERRED_VARIANT`)
+
+By default, the library uses the following preferred adaptive variant:
+
+```ts 
+    // DESKTOP_TO_FIRST or MOBILE_TO_FIRST
+    // TAdaptiveVariant = Dtf | MtF
+    export const PREFERRED_VARIANT: TAdaptiveVariant = 'DtF';  
+```
+
 #### Horizontal Breakpoints
 
 ```typescript
@@ -107,38 +113,29 @@ const MyComponent = () => {
 };
 ```
 
-#### Hook `useBreakpointMF`
-
-```typescript
-import { useBreakpointMF } from 'react-responsive-tools';
+#### Hook `useBreakpointBetween`
 
-// Usage Example
-const MyComponent = () => {
-    const isMedium = useBreakpointMF('md');
+`useBreakpointBetween` is an optimized hook for checking whether the current
+viewport is between two breakpoints (`min` and `max`).
 
-    return (
-        <div>
-            {isMedium && <p>Current breakpoint: Medium (md) for Mobile First</p>}
-        </div>
-    );
-};
-```
+It is especially useful as a safe replacement for combining `useBreakpoint`
+with both mobile-first (`For`) and desktop-first (`Before`) logic, where
+their ranges would otherwise overlap at the same pixel (for example,
+`min-width: 300px` and `max-width: 300px` both including 300px).
 
-#### Hook `useBreakpointDF`
+Internally the hook adjusts one of the boundaries by `1px` based on
+the preferred adaptive variant (`PREFERRED_VARIANT`) to ensure that
+a particular pixel falls into only one range.
 
 ```typescript
-import { useBreakpointDF } from 'react-responsive-tools';
-
-// Usage Example
-const MyComponent = () => {
-    const isLarge = useBreakpointDF('lg');
-
-    return (
-        <div>
-            {isLarge && <p>Current breakpoint: Large (lg) for Desktop First</p>}
-        </div>
-    );
-};
+    import { useBreakpointBetween } from 'react-responsive-tools';
+
+    const MyComponent = () => { 
+        const isVisible = useBreakpointBetween('sm', 'lg');
+        return (
+            {isVisible && Visible only between "sm" and "lg" breakpoints}
+        ); 
+    };
 ```
 
 #### Hook `useVBreakpoint`
@@ -158,40 +155,6 @@ const MyComponent = () => {
 };
 ```
 
-#### Hook `useVBreakpointMF`
-
-```typescript
-import { useVBreakpointMF } from 'react-responsive-tools';
-
-// Usage Example
-const MyComponent = () => {
-    const isMedium = useVBreakpointMF('md');
-
-    return (
-        <div>
-            {isMedium && <p>Current vertical breakpoint: Medium (md) for Mobile First</p>}
-        </div>
-    );
-};
-```
-
-#### Hook `useVBreakpointDF`
-
-```typescript
-import { useVBreakpointDF } from 'react-responsive-tools';
-
-// Usage Example
-const MyComponent = () => {
-    const isLarge = useVBreakpointDF('lg');
-
-    return (
-        <div>
-            {isLarge && <p>Current vertical breakpoint: Large (lg) for Desktop First</p>}
-        </div>
-    );
-};
-```
-
 ### Using Components
 
 #### Component `For`
@@ -232,6 +195,37 @@ const CustomSizeComponent = () => (
 );
 ```
 
+#### Component `Between`
+
+`Between` is a convenience component built on top of `useBreakpointBetween`.
+It renders its children only when the viewport width is between `min` and `max`.
+
+Compared to combining `For` and `Before`, `Between` automatically applies the
+1px shift logic to avoid overlapping ranges.
+
+```tsx
+import React from 'react';
+
+import { Between } from 'react-responsive-tools';
+
+/**
+ * Visible only on tablet widths: from "sm" (576px) up to "lg" (992px)
+ * with a safe 1px gap between adjacent ranges.
+ */
+export function TabletOnlyBanner() {
+    return (
+        <Between min="sm" max="lg">
+            <section className="tablet-banner">
+                <h2>Tablet-only promo</h2>
+                <p>
+                    This banner is visible only between the <code>sm</code> and <code>lg</code> breakpoints.
+                </p>
+            </section>
+        </Between>
+    );
+}
+```
+
 ### Breakpoint Types
 
 ```typescript

package/dist/breakpoints.config.d.ts

@@ -1,4 +1,20 @@
 import { TAdaptiveVariant } from "./interfaces/TAdaptiveVariant";
+/**
+ * Preferred adaptive layout variant.
+ *
+ * 'DtF' stands for "Desktop To First" and is used as the default strategy
+ * for resolving overlaps between "mobile-first" (`min-width`) and
+ * "desktop-first" (`max-width`) breakpoints.
+ *
+ * When switching between these variants we shift the opposite boundary
+ * by 1px to avoid cases when two ranges overlap at the exact same pixel.
+ *
+ * For example:
+ *  - `min-width: 300px` includes 300px,
+ *  - `max-width: 300px` also includes 300px,
+ * which causes an overlap. By shifting one of them by 1px we guarantee
+ * that a given pixel belongs to only one range.
+ */
 export declare const PREFERRED_VARIANT: TAdaptiveVariant;
 declare const HORIZONTAL_BREAKPOINTS: Record<string, string>;
 declare const VERTICAL_BREAKPOINTS: Record<string, string>;

package/dist/breakpoints.config.js

@@ -1,4 +1,20 @@
 // src/breakpoints.config.ts
+/**
+ * Preferred adaptive layout variant.
+ *
+ * 'DtF' stands for "Desktop To First" and is used as the default strategy
+ * for resolving overlaps between "mobile-first" (`min-width`) and
+ * "desktop-first" (`max-width`) breakpoints.
+ *
+ * When switching between these variants we shift the opposite boundary
+ * by 1px to avoid cases when two ranges overlap at the exact same pixel.
+ *
+ * For example:
+ *  - `min-width: 300px` includes 300px,
+ *  - `max-width: 300px` also includes 300px,
+ * which causes an overlap. By shifting one of them by 1px we guarantee
+ * that a given pixel belongs to only one range.
+ */
 export const PREFERRED_VARIANT = 'DtF'; // DESKTOP_TO_FIRST
 const HORIZONTAL_BREAKPOINTS = {
     "xs": "320px",

package/dist/components/horizontal.d.ts

@@ -12,7 +12,32 @@ interface BetweenProps {
     max: TBreakpoint | number;
     min: TBreakpoint | number;
 }
+/**
+ * Renders children only when the current viewport matches
+ * the given breakpoint using the mobile-first ("MtF") strategy.
+ *
+ * Internally it uses {@link useBreakpoint} with variant "MtF".
+ */
 export declare function For({ children, p }: Props): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Renders children only when the current viewport matches
+ * the given breakpoint using the desktop-first ("DtF") strategy.
+ *
+ * Internally it uses {@link useBreakpoint} with variant "DtF".
+ */
 export declare function Before({ children, p }: Props): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Renders children only when the current viewport is between
+ * two breakpoints (`min` and `max`).
+ *
+ * This component is an optimized alternative to combining `For`
+ * and `Before` when their ranges would overlap at the same pixel
+ * (e.g. `min-width: 300px` and `max-width: 300px` both including 300px).
+ *
+ * Under the hood it uses {@link useBreakpointBetween}, which shifts
+ * one of the boundaries by 1px depending on the preferred adaptive
+ * variant (see {@link PREFERRED_VARIANT}) to guarantee that a given
+ * pixel belongs to only one logical range.
+ */
 export declare function Between({ children, min, max }: BetweenProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/components/horizontal.js

@@ -3,19 +3,44 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * Created by westp on 15.05.2023
  */
 import { Fragment } from "react";
-import { useBreakpoint, useBreakpointBetween } from '../hooks/useBreakpoint.js';
+import { useBreakpoint, useBreakpointBetween } from '../hooks/useBreakpoint';
+/**
+ * Renders children only when the current viewport matches
+ * the given breakpoint using the mobile-first ("MtF") strategy.
+ *
+ * Internally it uses {@link useBreakpoint} with variant "MtF".
+ */
 export function For({ children, p }) {
     const is = useBreakpoint(p, 'MtF');
     if (is)
         return _jsx(Fragment, { children: children });
     return null;
 }
+/**
+ * Renders children only when the current viewport matches
+ * the given breakpoint using the desktop-first ("DtF") strategy.
+ *
+ * Internally it uses {@link useBreakpoint} with variant "DtF".
+ */
 export function Before({ children, p }) {
     const is = useBreakpoint(p, 'DtF');
     if (is)
         return _jsx(Fragment, { children: children });
     return null;
 }
+/**
+ * Renders children only when the current viewport is between
+ * two breakpoints (`min` and `max`).
+ *
+ * This component is an optimized alternative to combining `For`
+ * and `Before` when their ranges would overlap at the same pixel
+ * (e.g. `min-width: 300px` and `max-width: 300px` both including 300px).
+ *
+ * Under the hood it uses {@link useBreakpointBetween}, which shifts
+ * one of the boundaries by 1px depending on the preferred adaptive
+ * variant (see {@link PREFERRED_VARIANT}) to guarantee that a given
+ * pixel belongs to only one logical range.
+ */
 export function Between({ children, min, max }) {
     const is = useBreakpointBetween(min, max);
     if (is)

package/dist/hooks/useBreakpoint.d.ts

@@ -1,4 +1,53 @@
 import { TBreakpoint } from '../interfaces/TBreakpoint';
 import { TAdaptiveVariant } from '../interfaces/TAdaptiveVariant';
+/**
+ * Low-level hook that checks if the current viewport matches a horizontal breakpoint.
+ *
+ * It supports:
+ *  - named breakpoints (e.g. "md", "lg"),
+ *  - custom numeric pixel values (e.g. 768).
+ *
+ * The check is performed using `react-responsive` and the current adaptive variant:
+ *  - for mobile-first (MtF) the hook uses `min-width`,
+ *  - for desktop-first (DtF) the hook uses `max-width`.
+ *
+ * To avoid overlap between opposite variants (e.g. `min-width: 300px` and
+ * `max-width: 300px` both including 300px), the hook shifts the opposite
+ * boundary by 1px when the requested variant differs from `PREFERRED_VARIANT`.
+ *
+ * @param b Breakpoint name or explicit pixel value.
+ * @param variant Adaptive variant: "MtF" (mobile to first) or "DtF" (desktop to first).
+ *                By default, uses {@link PREFERRED_VARIANT}.
+ * @returns `true` if the media query matches, otherwise `false` or `null`
+ *          (depending on `react-responsive` behavior).
+ */
 export declare function useBreakpoint(b: TBreakpoint | number, variant?: TAdaptiveVariant): boolean | null;
+/**
+ * Optimized hook for checking if the current viewport is between two breakpoints.
+ *
+ * This hook is designed as a safe alternative to using a combination of
+ * `For` (mobile-first) and `Before` (desktop-first) when their ranges would
+ * otherwise overlap.
+ *
+ * Example of the overlap problem:
+ *  - `min-width: 300px` includes 300px,
+ *  - `max-width: 300px` also includes 300px,
+ * so both conditions are `true` at exactly 300px.
+ *
+ * To prevent this, {@link useBreakpointBetween} automatically shifts the
+ * opposite boundary by 1px depending on the adaptive variant:
+ *
+ *  - preferredVariant === "MtF":
+ *      max = max - 1 (so the upper bound becomes exclusive by 1px),
+ *  - preferredVariant === "DtF":
+ *      min = min - 1 (so the lower bound becomes exclusive by 1px),
+ *
+ * ensuring that a particular pixel belongs to only one logical range.
+ *
+ * @param min Lower breakpoint (inclusive in the original definition).
+ * @param max Upper breakpoint (inclusive in the original definition).
+ * @param preferredVariant Adaptive variant used to resolve the 1px overlap.
+ *                         By default, uses {@link PREFERRED_VARIANT}.
+ * @returns `true` if the viewport width is within the adjusted [min, max] range.
+ */
 export declare function useBreakpointBetween(min: TBreakpoint | number, max: TBreakpoint | number, preferredVariant?: TAdaptiveVariant): boolean;

package/dist/hooks/useBreakpoint.js

@@ -2,6 +2,27 @@ import { useMediaQuery } from 'react-responsive';
 import { PREFERRED_VARIANT } from '../breakpoints.config';
 import useVariant from './useVariant';
 import { getBreakpoint } from "../functions/getBreakpoint";
+/**
+ * Low-level hook that checks if the current viewport matches a horizontal breakpoint.
+ *
+ * It supports:
+ *  - named breakpoints (e.g. "md", "lg"),
+ *  - custom numeric pixel values (e.g. 768).
+ *
+ * The check is performed using `react-responsive` and the current adaptive variant:
+ *  - for mobile-first (MtF) the hook uses `min-width`,
+ *  - for desktop-first (DtF) the hook uses `max-width`.
+ *
+ * To avoid overlap between opposite variants (e.g. `min-width: 300px` and
+ * `max-width: 300px` both including 300px), the hook shifts the opposite
+ * boundary by 1px when the requested variant differs from `PREFERRED_VARIANT`.
+ *
+ * @param b Breakpoint name or explicit pixel value.
+ * @param variant Adaptive variant: "MtF" (mobile to first) or "DtF" (desktop to first).
+ *                By default, uses {@link PREFERRED_VARIANT}.
+ * @returns `true` if the media query matches, otherwise `false` or `null`
+ *          (depending on `react-responsive` behavior).
+ */
 export function useBreakpoint(b, variant = PREFERRED_VARIANT) {
     let _bp = typeof b === 'number' ? b : +getBreakpoint(b);
     const v = useVariant(variant);
@@ -9,6 +30,34 @@ export function useBreakpoint(b, variant = PREFERRED_VARIANT) {
         _bp = _bp - 1;
     return useMediaQuery({ query: `(${v}-width: ${_bp}px)` });
 }
+/**
+ * Optimized hook for checking if the current viewport is between two breakpoints.
+ *
+ * This hook is designed as a safe alternative to using a combination of
+ * `For` (mobile-first) and `Before` (desktop-first) when their ranges would
+ * otherwise overlap.
+ *
+ * Example of the overlap problem:
+ *  - `min-width: 300px` includes 300px,
+ *  - `max-width: 300px` also includes 300px,
+ * so both conditions are `true` at exactly 300px.
+ *
+ * To prevent this, {@link useBreakpointBetween} automatically shifts the
+ * opposite boundary by 1px depending on the adaptive variant:
+ *
+ *  - preferredVariant === "MtF":
+ *      max = max - 1 (so the upper bound becomes exclusive by 1px),
+ *  - preferredVariant === "DtF":
+ *      min = min - 1 (so the lower bound becomes exclusive by 1px),
+ *
+ * ensuring that a particular pixel belongs to only one logical range.
+ *
+ * @param min Lower breakpoint (inclusive in the original definition).
+ * @param max Upper breakpoint (inclusive in the original definition).
+ * @param preferredVariant Adaptive variant used to resolve the 1px overlap.
+ *                         By default, uses {@link PREFERRED_VARIANT}.
+ * @returns `true` if the viewport width is within the adjusted [min, max] range.
+ */
 export function useBreakpointBetween(min, max, preferredVariant = PREFERRED_VARIANT) {
     let _min = typeof min === 'number' ? min : +getBreakpoint(min);
     let _max = typeof max === 'number' ? max : +getBreakpoint(max);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-responsive-tools",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.js",