Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mathewsmachado/styled-query-builder
💅 A semantic tool to help you build responsive interfaces with Styled Components.
https://github.com/mathewsmachado/styled-query-builder
styled-components
Last synced: about 1 month ago
JSON representation
💅 A semantic tool to help you build responsive interfaces with Styled Components.
- Host: GitHub
- URL: https://github.com/mathewsmachado/styled-query-builder
- Owner: mathewsmachado
- License: mit
- Created: 2021-05-16T03:25:12.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2021-11-01T16:38:15.000Z (about 3 years ago)
- Last Synced: 2024-10-10T19:04:55.198Z (about 1 month ago)
- Topics: styled-components
- Language: TypeScript
- Homepage:
- Size: 1.63 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
styled-query-builder 🔨
Sometimes, working with media queries isn't easy. It's hard to remember what "min-width" or "max-width" stand for, if the styles will be applied if the screen is smaller or bigger than the specified. This is what [styled-query-builder](https://github.com/MathewsMachado/styled-query-builder) aims to solve. With this tool, you can write media queries in a semantic way.
[styled-query-builder](https://github.com/MathewsMachado/styled-query-builder) is a library made to work alongside [styled-components](https://styled-components.com).
## Why use it?
It is easy to use, well-documented and tested!
## Features
- [Pre-configured media queries](https://github.com/MathewsMachado/styled-query-builder/#usage)
- [Custom media queries](https://github.com/MathewsMachado/styled-query-builder/#builderuserbreakpoints-sizeunit)
- [Semantic API](https://github.com/MathewsMachado/styled-query-builder/#api)
- [Flexibility to work with what you like most, mobile-first or desktop-first](https://github.com/MathewsMachado/styled-query-builder/#api)
- [A helper that gives you all the available media queries](https://github.com/MathewsMachado/styled-query-builder/#breakpointsmediaquerytype-sizes-antioverlap)
- [Media queries that do not overlap with each other thanks to the "antiOverlap" property](https://github.com/MathewsMachado/styled-query-builder/#antioverlap)
## Getting Started
### Pre-requisites
You need to be on a project that has [styled-components](https://styled-components.com/) as a dependency.
### Installation
You can install [styled-query-builder](https://github.com/MathewsMachado/styled-query-builder) with [npm](https://github.com/npm/cli)
```sh
npm install styled-query-builder
```
or with [yarn](https://github.com/yarnpkg/berry)
```sh
yarn add styled-query-builder
```
## Usage
This library has, as default, the following breakpoints:
and "px" as size unit.
### Disclaimer
1. If you want to use "rem" as size unit, you will have to use the ["builder()"](https://github.com/MathewsMachado/styled-query-builder/#builderuserbreakpoints-sizeunit) method.
2. If you want to call the methods as in:
but want different breakpoints, you will also have to use the ["builder()"](https://github.com/MathewsMachado/styled-query-builder/#builderuserbreakpoints-sizeunit) method. Otherwise, if you want to use different breakpoints, but don't care about calling the methods as above, you can call them as in:
### API
#### **[above](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/mediaQuery/index.ts)([size](https://github.com/MathewsMachado/styled-query-builder/#size), [antiOverlap?](https://github.com/MathewsMachado/styled-query-builder/#antioverlap))**
This function applies the style if the screen is bigger than the informed size. It is equivalent to "`@media (min-width: ...)`".
#### **[below](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/mediaQuery/index.ts)([size](https://github.com/MathewsMachado/styled-query-builder/#size), [antiOverlap?](https://github.com/MathewsMachado/styled-query-builder/#antioverlap))**
This function applies the style if the screen is smaller than the informed size. It is equivalent to "`@media (max-width: ...)`".
#### **[between](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/mediaQuery/index.ts)([sizes](https://github.com/MathewsMachado/styled-query-builder/#sizes))**
This function applies the style if the screen size is between the informed sizes. It is equivalent to "`@media (min-width: ...) and (max-width: ...)`".
#### **[breakpoints](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/breakpoint/index.ts#L74)([mediaQueryType](https://github.com/MathewsMachado/styled-query-builder/#mediaquerytype), [sizes](https://github.com/MathewsMachado/styled-query-builder/#sizes), [antiOverlap?](https://github.com/MathewsMachado/styled-query-builder/#antioverlap))**
This function returns the media query that the user wants. It is perfect to mock a size screen in tests that uses [jest-styled-components](https://github.com/styled-components/jest-styled-components), and a lot more.
#### **[builder](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/builder/index.ts)([userBreakpoints](https://github.com/MathewsMachado/styled-query-builder/#userbreakpoints), [sizeUnit](https://github.com/MathewsMachado/styled-query-builder/#sizeunit))**
This function is for who wants custom breakpoints or use "rem" as size unit. You load it with the breakpoints and the size unit, and it returns all the above methods to you: "[above()](https://github.com/MathewsMachado/styled-query-builder/#abovesize-antioverlap)", "[below()](https://github.com/MathewsMachado/styled-query-builder/#belowsize-antioverlap)", "[between()](https://github.com/MathewsMachado/styled-query-builder/#betweensizes)" and "[breakpoints()](https://github.com/MathewsMachado/styled-query-builder/#breakpointsmediaquerytype-sizes-antioverlap)".
### Functions Parameters
#### **[antiOverlap?](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/types.d.ts)**
If, somehow, you use two media queries that "bump" each other, like:
You can use this property to solve this issue. If you are calling the "[below()](https://github.com/MathewsMachado/styled-query-builder/#belowsize-antioverlap)" method, it will reduce from the media query the value that you pass. If you are calling the "[above()](https://github.com/MathewsMachado/styled-query-builder/#abovesize-antioverlap)" method, it will add to the media query the value that you pass.
#### **[mediaQueryType](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/types.ts)**
It can be the following values: "above", "below" or "between".
#### **[size](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/types.ts)**
It can be one of the keys of the breakpoints (the default ones or the ones provided by the user), or a value indicating a size.
#### **[sizes](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/types.ts)**
It can be a [size](https://github.com/MathewsMachado/styled-query-builder/#size) or a [size array](https://github.com/MathewsMachado/styled-query-builder/#size) with two values.
#### **[sizeUnit](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/types.ts)**
It can be the following values: "px" or "rem".
#### **[userBreakpoints](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/types.ts)**
It can be an object like the [default breakpoints](https://github.com/MathewsMachado/styled-query-builder/#usage), with how many breakpoints the user wants.
## Examples
This README file has only simple examples. If you want more, take a look at the [examples](https://github.com/MathewsMachado/styled-query-builder/tree/main/docs/examples) folder and run them by yourself.
Basic step:
```sh
git clone https://github.com/MathewsMachado/styled-query-builder.git && \
cd styled-query-builder && \
yarn
```
- To run the [above](https://github.com/MathewsMachado/styled-query-builder/tree/main/docs/examples/above) example: `cd docs/examples/above && yarn && yarn start`
- To run the [antiOverlap](https://github.com/MathewsMachado/styled-query-builder/tree/main/docs/examples/antiOverlap) example: `cd docs/examples/antiOverlap && yarn && yarn start`
- To run the [below](https://github.com/MathewsMachado/styled-query-builder/tree/main/docs/examples/below) example: `cd docs/examples/below && yarn && yarn start`
- To run the [between](between) example: `cd docs/examples/between && yarn && yarn start`
- To run the [breakpoints](https://github.com/MathewsMachado/styled-query-builder/tree/main/docs/examples/breakpoints) example: `cd docs/examples/breakpoints && yarn && yarn start`
- To run the [builder](https://github.com/MathewsMachado/styled-query-builder/tree/main/docs/examples/builder) example: `cd docs/examples/builder && yarn && yarn start`
## To-Do
- Improve regex at ["hasLettersAndNumbers"](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/helpers).
- Docs: Fix the Eslint error that only allows the examples to run if there are the node_modules folder in the root directory.
- Tests: Look for general improvements.
- Typing: Improve typing. Now, there are no code completion and no syntax highlight due to it.
- Typing: Integrate better with [styled-components](https://styled-components.com/).
- Typing: Fix the errors across the codebase, which are marked as "// typescript issue". The items 2, 3 and 4 below are related and on the same file.
1. on [mediaQueryTypeMapper](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/breakpoint/index.ts)
2. on [mediaQuery tests](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/mediaQuery/test.tsx)
3. on [mediaQuery tests](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/mediaQuery/test.tsx)
4. on [mediaQuery tests](https://github.com/MathewsMachado/styled-query-builder/blob/main/src/mediaQuery/test.tsx)
## Contribution
This project is accepting contributions, the aim is to clean the [to-do](https://github.com/MathewsMachado/styled-query-builder/#to-do) list. We are really needing help with typing.
Feel free to open an issue or submit a pull request. In the case of a pull request, explain well what you are doing and create tests for it.
## Acknowledgement
This project was inspired by [Morajabi's](https://github.com/morajabi) library, [styled-media-query](https://github.com/morajabi/styled-media-query).
I want to thanks [Willian Machado](https://www.linkedin.com/in/willian-machado-amorim/) for having done the library [logo](https://github.com/MathewsMachado/styled-query-builder/blob/main/docs/images/logo-background.png) and proofreading this README.
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/MathewsMachado/styled-query-builder/blob/main/LICENSE) file for details.