react-responsive-tools 1.1.5 → 2.0.1

package/README.MD

@@ -1,10 +1,8 @@
 # react-responsive-tools
 
-This project provides tools and configurations to simplify writing responsive code for both vertical and horizontal layouts.
+This project provides tools and configurations to simplify writing adaptive code for both vertical and horizontal layouts.
 
-The package is based on the npm package [react-responsive](https://www.npmjs.com/package/react-responsive) for use in React.js. It assumes the use of scss for compilation.
-
-In the future, the dependency on scss will be removed.
+The package is based on [react-responsive](https://www.npmjs.com/package/react-responsive) for use in React. It assumes the use of SCSS for compilation.
 
 ## Installation
 
@@ -18,249 +16,609 @@ yarn add react-responsive-tools
 npm install react-responsive-tools
 ```
 
-To initialize the tools, you need to import the file from the library:
+### Import SCSS
+
+To use the generated SCSS files, import the main SCSS file from the library:
 
 ```scss
-@import "react-responsive-tools/default"; // init breakpoints
+@import 'react-responsive-tools';
 ```
 
-This line imports the necessary CSS variables (breakpoints) required for the tools to work.
+### Import JavaScript
 
-The package also includes a file to reset browser styles:
+To use the components and hooks, import them from the library:
 
-```scss
-@import "react-responsive-tools/reset"; // reset browsers styles
+```javascript
+import { For, Before, useBreakpoint, useBreakpointDF, useBreakpointMF, useVBreakpoint, useVBreakpointDF, useVBreakpointMF } from 'react-responsive-tools';
 ```
 
-### Default Horizontal and Vertical Breakpoints:
-
---vbp - vertical breakpoints
+## Initialization and Configuration
 
---bp - horizontal breakpoints
+To initialize the tools, use the following commands:
 
-```scss
-:root {
-  --bp-xs: 320px;
-  --bp-sm: 576px;
-  --bp-md: 768px;
-  --bp-lg: 992px;
-  --bp-lt: 1024px;
-  --bp-ltm: 1120px;
-  --bp-ltl: 1440px;
-  --bp-xl: 1920px;
-  --bp-xxl: 2560px;
-  --bp-qxl: 3840px;
-
-  --vbp-xs: 600px;
-  --vbp-sm: 800px;
-  --vbp-md: 1000px;
-  --vbp-lg: 1200px;
-  --vbp-xl: 1600px;
-  --vbp-xxl: 1920px;
-}
-```
+### Re-initializing Configuration
 
-Breakpoints override example:
+If you have changed the configuration or added new settings, you need to reinitialize the configuration files. To do this, run the following command:
 
-```scss
-@import "react-responsive-tools/default"; // init breakpoints
-
-:root {
-  //--bp-xxl: 2560px;
-  --bp-xxl: 2222px; // new point
-}
+```sh
+react-responsive-tools run reinit
 ```
 
-## Using Mixins
+This command will run the `reinit.sh` script, which will recreate the necessary configuration files.
 
-Mixins are packaged with an `include` decorator that provides descriptive instructions for breakpoints.
+### Default Values
 
-Example:
+The following horizontal and vertical breakpoints are provided by default:
 
-```scss
-@import "react-responsive-tools";
+#### Horizontal Breakpoints
 
-div.supercool {
-  @include m-xs { // for mobile to first xs breakpoint
-    color: red;
-    font-size: 10px;
-    @include vm-sm {
-      font-size: 11px;
-    }
-    @include vm-md {
-      font-size: 14px;
-    }
-  }
-}
+```typescript
+export const HORIZONTAL_BREAKPOINTS = {
+  xs: '320px',
+  sm: '576px',
+  md: '768px',
+  lg: '992px',
+  lt: '1024px',
+  ltm: '1200px',
+  ltl: '1440px',
+  xl: '1920px',
+  xxl: '2560px',
+  qxl: '3840px',
+};
+```
 
-span.someclass {
-  @include d-xxl { // for desktop to first xxl breakpoint
-    color: white;
-    // vertical points in horizontal 
-    @include vd-xs {
-      font-size: 10px;
-    }
-    @include vd-md {
-      font-size: 12px;
-    }
-  }
-}
+#### Vertical Breakpoints
 
-aside.sidebar {
-  // custom breakpoint
-  @include mob-first(xs) {
-    ...
-  }
-  // desktop to first
-  @include desk-first(md) {
-    ...
-  }
+```typescript
+export const VERTICAL_BREAKPOINTS = {
+  xs: '600px',
+  sm: '800px',
+  md: '1000px',
+  lg: '1200px',
+  xl: '1600px',
+  xxl: '1920px',
+};
+```
 
-  // vertical custom bp
-  @include v-desk-first(md) {
+### Using Hooks
 
-  }
-  // mob first
-  @include v-mob-first(md) {
+#### Hook `useBreakpoint`
 
-  }
-}
-```
+```typescript
+import { useBreakpoint } from 'react-responsive-tools';
 
-## Hooks
+// Usage Example
+const MyComponent = () => {
+    const isMedium = useBreakpoint('md');
 
-### Hook Implementations
+    return (
+        <div>
+            {isMedium && <p>Current breakpoint: Medium (md)</p>}
+        </div>
+    );
+};
+```
 
-#### Hook `useBreakpoint`:
+#### Hook `useBreakpointMF`
 
 ```typescript
-import { useMediaQuery } from 'react-responsive';
-import breakpoints from '../../scss/_horizontal.export.scss';
-import { TBreakpoint } from '../../interfaces/TBreakpoint';
-import { TAdaptiveVariant } from '../../interfaces/TAdaptiveVariant';
-import useVariant from '../useVariant';
+import { useBreakpointMF } from 'react-responsive-tools';
 
-export default function useBreakpoint(b: TBreakpoint, variant: TAdaptiveVariant = 'MtF') {
-    const p = breakpoints[b];
-    const v = useVariant(variant);
-    return useMediaQuery({ query: `(${v}-width: ${p}px)` });
-}
-
-export function useBreakpointMF(b: TBreakpoint) {
-    return useBreakpoint(b, 'MtF');
-}
+// Usage Example
+const MyComponent = () => {
+    const isMedium = useBreakpointMF('md');
 
-export function useBreakpointDF(b: TBreakpoint) {
-    return useBreakpoint(b, 'DtF');
-}
+    return (
+        <div>
+            {isMedium && <p>Current breakpoint: Medium (md) for Mobile First</p>}
+        </div>
+    );
+};
 ```
 
-### Usage Examples
-
-#### Hook `useBreakpoint`:
+#### Hook `useBreakpointDF`
 
 ```typescript
-import useBreakpoint from './hooks/useBreakpoint';
+import { useBreakpointDF } from 'react-responsive-tools';
 
+// Usage Example
 const MyComponent = () => {
-    const isMedium = useBreakpoint('md');
+    const isLarge = useBreakpointDF('lg');
 
     return (
         <div>
-            {isMedium && <p>Current breakpoint: Medium (md)</p>}
+            {isLarge && <p>Current breakpoint: Large (lg) for Desktop First</p>}
         </div>
     );
 };
 ```
 
-#### Hook `useBreakpointMF`:
+#### Hook `useVBreakpoint`
 
 ```typescript
-import { useBreakpointMF } from './hooks/useBreakpoint';
+import { useVBreakpoint } from 'react-responsive-tools';
 
+// Usage Example
 const MyComponent = () => {
-    const isMedium = useBreakpointMF('md');
+    const isMedium = useVBreakpoint('md');
 
     return (
         <div>
-            {isMedium && <p>Current breakpoint: Medium (md) for Mobile First</p>}
+            {isMedium && <p>Current vertical breakpoint: Medium (md)</p>}
         </div>
     );
 };
 ```
 
-#### Hook `useBreakpointDF`:
+#### Hook `useVBreakpointMF`
 
 ```typescript
-import { useBreakpointDF } from './hooks/useBreakpoint';
+import { useVBreakpointMF } from 'react-responsive-tools';
 
+// Usage Example
 const MyComponent = () => {
-    const isLarge = useBreakpointDF('lg');
+    const isMedium = useVBreakpointMF('md');
 
     return (
         <div>
-            {isLarge && <p>Current breakpoint: Large (lg) for Desktop First</p>}
+            {isMedium && <p>Current vertical breakpoint: Medium (md) for Mobile First</p>}
         </div>
     );
 };
 ```
 
-## Components
+#### Hook `useVBreakpointDF`
 
-The project includes utility components to display content only at certain breakpoints.
+```typescript
+import { useVBreakpointDF } from 'react-responsive-tools';
 
-### Usage Examples
+// Usage Example
+const MyComponent = () => {
+    const isLarge = useVBreakpointDF('lg');
 
-#### Component `ForMF`:
+    return (
+        <div>
+            {isLarge && <p>Current vertical breakpoint: Large (lg) for Desktop First</p>}
+        </div>
+    );
+};
+```
+
+### Using Components
+
+#### Component `For`
 
 ```typescript
-import { ForMF } from './components/ForMF';
+import { For } from 'react-responsive-tools';
 
+// Usage Example
 const MyComponent = () => (
-    <ForMF bp='md'>
+    <For p='md'>
         <p>This content is visible only at the Medium (md) breakpoint</p>
-    </ForMF>
+    </For>
 );
 
 const CustomSizeComponent = () => (
-    <ForMF bp={850}>
+    <For p={850}>
         <p>This content is visible only at the Custom (850px) breakpoint</p>
-    </ForMF>
+    </For>
 );
 ```
 
-#### Component `ForDF`:
+#### Component `Before`
 
 ```typescript
-import { ForDF } from './components/ForDF';
+import { Before } from 'react-responsive-tools';
 
+// Usage Example
 const MyComponent = () => (
-    <ForDF bp='lg'>
+    <Before p='lg'>
         <p>This content is visible only at the Large (lg) breakpoint</p>
-    </ForDF>
+    </Before>
 );
 
 const CustomSizeComponent = () => (
-    <ForDF bp={1200}>
+    <Before p={1200}>
         <p>This content is visible only at the Custom (1200px) breakpoint</p>
-    </ForDF>
+    </Before>
 );
 ```
 
-## Project Structure
+### Breakpoint Types
+
+```typescript
+export type TBreakpoint =
+    | 'xs'
+    | 'sm'
+    | 'md'
+    | 'lg'
+    | 'lt'
+    | 'ltm'
+    | 'ltl'
+    | 'xl'
+    | 'xxl'
+    | 'qxl'
+
+export type TVerticalBreakpoint =
+    | 'xs'
+    | 'sm'
+    | 'md'
+    | 'lg'
+    | 'xl'
+    | 'xxl'
+```
+
+### Project Structure
+
+The project includes the following directories and files:
+
+- `scss`: directory for SCSS files.
+    - `_custom-breakpoints.scss`: contains custom breakpoints.
+    - `_horizontal.scss`: provides mixins for horizontal layouts.
+    - `_horizontal-breakpoints.scss`: defines horizontal breakpoints.
+    - `_vertical.scss`: provides mixins for vertical layouts.
+    - `_vertical-breakpoints.scss`: defines vertical breakpoints.
+    - `index.scss`: main SCSS file.
+
+- `hooks`: directory for hooks.
+    - `useBreakpoint.ts`: implements the `useBreakpoint` hook.
+    - `useVBreakpoint.ts`: implements the `useVBreakpoint` hook.
+    - `useVariant.ts`: utility hook to determine the variant.
+
+- `components`: directory for components.
+    - `horizontal.tsx`: utility components for horizontal layouts.
+    - `For.tsx`: utility component for displaying content at a specific breakpoint.
+    - `Before.tsx`: utility component similar to `For`, but for different breakpoints.
+
+- `scripts`: directory for scripts.
+    - `createConfig.js`: script to create configuration files.
+    - `generateCustomBreakpointsSCSS.js`: script to generate custom SCSS breakpoints.
+    - `generateSCSS.js`: script to generate SCSS files.
+    - `generateTBreakpoint.js`: script to generate TypeScript breakpoint types.
+
+- `interfaces`: directory for TypeScript interfaces.
+    - `TAdaptiveVariant.ts`: interface for adaptive variant types.
+    - `TBreakpoint.ts`: interface for breakpoint types.
+    - `TBreakpoints.ts`: interface for breakpoints.
+
+## Command Line Interface (CLI)
+
+To recreate the necessary files, run the provided script using the following command:
+
+```sh
+react-responsive-tools run reinit
+```
+
+This command will run the `reinit.sh` script, which will create the configuration files for the project.
+
+### Examples of SCSS Mixins after Re-initialization
+
+After re-generating the files, the following SCSS mixins will be available:
+
+#### Horizontal Breakpoints
+
+```scss
+@import "_custom-breakpoints";
+
+@mixin mob-first($breakpoint) {
+  @media (min-width: map-get($horizontal-breakpoints, $breakpoint)) {
+    @content;
+  }
+}
+
+@mixin desk-first($breakpoint) {
+  @media (max-width: map-get($horizontal-breakpoints, $breakpoint)) {
+    @content;
+  }
+}
+
+// Example mixins
+@mixin for-xs() {
+  @include mob-first(xs) {
+    @content;
+  }
+}
+
+@mixin for-sm() {
+  @include mob-first(sm) {
+    @content;
+  }
+}
+
+@mixin for-md() {
+  @include mob-first(md) {
+    @content;
+  }
+}
+
+@mixin for-lg() {
+  @include mob-first(lg) {
+    @content;
+  }
+}
+
+@mixin for-lt() {
+  @include mob-first(lt) {
+    @content;
+  }
+}
+
+@mixin for-ltm() {
+  @include mob-first(ltm) {
+    @content;
+  }
+}
+
+@mixin for-ltl() {
+  @include mob-first(ltl) {
+    @content;
+  }
+}
+
+@mixin for-xl() {
+  @include mob-first(xl) {
+    @content;
+  }
+}
+
+@mixin for-xxl() {
+  @include mob-first(xxl) {
+    @content;
+  }
+}
+
+@mixin for-qxl() {
+  @include mob-first(qxl) {
+    @content;
+  }
+}
+
+@mixin before-xs() {
+  @include desk-first(xs) {
+    @content;
+  }
+}
+
+@mixin before-sm() {
+  @include desk-first(sm) {
+    @content;
+  }
+}
+
+@mixin before-md() {
+  @include desk-first(md) {
+    @content;
+  }
+}
+
+@mixin before-lg() {
+  @include desk-first(lg) {
+    @content;
+  }
+}
+
+@mixin before-lt() {
+  @include desk-first(lt) {
+    @content;
+  }
+}
+
+@mixin before-ltm() {
+  @include desk-first(ltm) {
+    @content;
+  }
+}
+
+@mixin before-ltl() {
+  @include desk-first(ltl) {
+    @content;
+  }
+}
+
+@mixin before-xl() {
+  @include desk-first(xl) {
+    @content;
+  }
+}
+
+@mixin before-xxl() {
+  @include desk-first(xxl) {
+    @content;
+  }
+}
+
+@mixin before-qxl() {
+  @include desk-first(qxl) {
+    @content;
+  }
+}
+```
+
+#### Vertical Breakpoints
+
+```scss
+@import "_custom-breakpoints";
+
+@mixin v-mob-first($breakpoint) {
+  @media (min-height: map-get($vertical-breakpoints, $breakpoint)) {
+    @content;
+  }
+}
+
+@mixin v-desk-first($breakpoint) {
+  @media (max-height: map-get($vertical-breakpoints, $breakpoint)) {
+    @content;
+  }
+}
+
+// Example mixins
+@mixin v-for-xs() {
+  @include v-mob-first(xs) {
+    @content;
+  }
+}
+
+@mixin v-for-sm() {
+  @include v-mob-first(sm) {
+    @content;
+  }
+}
+
+@mixin v-for-md() {
+  @include v-mob-first(md) {
+    @content;
+  }
+}
+
+@mixin v-for-lg() {
+  @include v-mob-first(lg) {
+    @content;
+  }
+}
+
+@mixin v-for-xl() {
+  @include v-mob-first(xl) {
+    @content;
+  }
+}
+
+@mixin v-for-xxl() {
+  @include v-mob-first(xxl) {
+    @content;
+  }
+}
+
+@mixin v-before-xs() {
+  @include v-desk-first(xs) {
+    @content;
+  }
+}
+
+@mixin v-before-sm() {
+  @include v-desk-first(sm) {
+    @content;
+  }
+}
+
+@mixin v-before-md() {
+  @include v-desk-first(md) {
+    @content;
+  }
+}
+
+@mixin v-before-lg() {
+  @include v-desk-first(lg) {
+    @content;
+  }
+}
+
+@mixin v-before-xl() {
+  @include v-desk-first(xl) {
+    @content;
+  }
+}
+
+@mixin v-before-xxl() {
+  @include v-desk-first(xxl) {
+    @content;
+  }
+}
+```
+
+### Practical Example of Using These Mixins
+
+Here is an example of how to use these mixins in your SCSS code:
+
+#### Horizontal Layout
+
+```scss
+.container {
+  // Base styles
+  width: 100%;
+  padding: 20px;
+
+  // Styles for `sm` breakpoint
+  @include for-sm {
+    width: 90%;
+    padding: 15px;
+  }
+
+  // Styles for `md` breakpoint
+  @include for-md {
+    width: 80%;
+    padding: 10px;
+  }
+
+  // Styles for `lg` breakpoint
+  @include for-lg {
+    width: 70%;
+    padding: 5px;
+  }
+}
+
+.header {
+  // Base styles
+  font-size: 16px;
+  background-color: white;
+
+  // Styles for `sm` breakpoint
+  @include before-sm {
+    font-size: 18px;
+    background-color: lightgray;
+  }
+
+  // Styles for `md` breakpoint
+  @include before-md {
+    font-size: 20px;
+    background-color: gray;
+  }
+}
+```
+
+#### Vertical Layout
 
-The project includes the `scss` directory with the following files:
+```scss
+.panel {
+  // Base styles
+  height: 100%;
+  padding: 20px;
+
+  // Styles for `sm` vertical breakpoint
+  @include v-for-sm {
+    height: 90%;
+    padding: 15px;
+  }
 
-- `_data.scss`: Contains breakpoints.
-- `_horizontal.scss` and `_vertical.scss`: Provide mixins for horizontal and vertical layouts, respectively.
-- `_screen.scss`: Intermediate file for export to JS.
+  // Styles for `md` vertical breakpoint
+  @include v-for-md {
+    height: 80%;
+    padding: 10px;
+  }
 
-The `hooks` directory includes:
+  // Styles for `lg` vertical breakpoint
+  @include v-for-lg {
+    height: 70%;
+    padding: 5px;
+  }
+}
 
-- `useBreakpoint.ts`: Implements the `useBreakpoint` hook to determine the current breakpoint.
-- `useVBreakpoint.ts`: Implements the `useVBreakpoint` hook to determine the current vertical breakpoint.
+.footer {
+  // Base styles
+  font-size: 16px;
+  background-color: white;
+
+  // Styles for `sm` vertical breakpoint
+  @include v-before-sm {
+    font-size: 18px;
+    background-color: lightgray;
+  }
 
-The `components` directory includes:
+  // Styles for `md` vertical breakpoint
+  @include v-before-md {
+    font-size: 20px;
+    background-color: gray;
+  }
+}
+```
 
-- `ForMF.ts`: A utility component that takes a breakpoint size and children as props. It uses the `useBreakpointMF` hook to determine if the screen size matches the given breakpoint. If it does, it renders the children; otherwise, it renders `null`.
-- `ForDF.ts`: Similar to `ForMF`, but uses the `useBreakpointDF` hook.
+Now, the documentation is complete with examples of using the `for` and `before` mixins for both horizontal and vertical breakpoints, as well as the native mobile-first and desktop-first mixins.