From b70a1e9b8ce86d5a302d29e7ef60e7eb8870c672 Mon Sep 17 00:00:00 2001 From: mg901 Date: Sat, 8 Jul 2023 11:23:26 +0400 Subject: [PATCH] fix(docs): reorganize documentation structure (#1546) * feat: add aliases for media queries * fix(docs): reorganize the documentation structure --- README.md | 93 ++-- docs/v11.x.x-README.md | 425 ------------------ .../create-styled-breakpoints-theme.d.ts | 45 +- styled-breakpoints/index.d.ts | 6 +- 4 files changed, 75 insertions(+), 494 deletions(-) delete mode 100644 docs/v11.x.x-README.md diff --git a/README.md b/README.md index 45db4d8f..0c0fcdb9 100644 --- a/README.md +++ b/README.md @@ -109,10 +109,10 @@ From largest to smallest ## Documentation +- core concepts +- available breakpoints - [quick start](#quick-start) -- [migration from v11](#migration-from-v11) -- [core concepts](#core-concepts) -- [available breakpoints](#available-breakpoints) +- migration from v11 - [media queries](#media-queries) - [min-width](#min-width) - [max-width](#max-width) @@ -120,11 +120,40 @@ From largest to smallest - [between breakpoints](#between-breakpoints) - [useMediaQuery hook](#usemediaquery-hook) - [customization](#customization) - - [strict typed breakpoints](#strict-typed-breakpoints) - - [merge with another theme](#merge-with-another-theme) + - strict typed breakpoints + - merge with another theme
+

Core concepts

 + +- **Breakpoints act as the fundamental elements of responsive design**. They enable you to control when your layout can adapt to a specific viewport or device size. + +- **Utilize media queries to structure your CSS based on breakpoints**. Media queries are CSS features that allow you to selectively apply styles depending on a defined set of browser and operating system parameters. The most commonly used media query property is min-width. + +- **The objective is mobile-first, responsive design**. Styled Breakpoints aims to apply the essential styles required for a layout to function at the smallest breakpoint. Additional styles are then added to adjust the design for larger devices. This approach optimizes your CSS, enhances rendering speed, and delivers an excellent user experience. + +
+ +

Available breakpoints

 + +Styled Breakpoints includes six default breakpoints, often referred to as grid tiers, for building responsive designs. These breakpoints can be [customized](#customization). + +Each breakpoint has been carefully selected to accommodate containers with widths that are multiples of 12. The breakpoints also represent a subset of common device sizes and viewport dimensions, although they do not specifically target every use case or device. Instead, they provide a robust and consistent foundation for building designs that cater to nearly any device. + +```tsx +const breakpoints = { + xs: '0px', + sm: '576px', + md: '768px', + lg: '992px', + xl: '1200px', + xxl: '1400px', +}; +``` + +
+ ## Quick start

πŸ’… Styled Components

 @@ -232,7 +261,7 @@ const App = () => (
-## Migration from v11 +

🏎️  Migration from v11.2.3

 ### Theme @@ -296,36 +325,7 @@ or + } ``` -
- -## Core concepts - -- **Breakpoints act as the fundamental elements of responsive design**. They enable you to control when your layout can adapt to a specific viewport or device size. - -- **Utilize media queries to structure your CSS based on breakpoints**. Media queries are CSS features that allow you to selectively apply styles depending on a defined set of browser and operating system parameters. The most commonly used media query property is min-width. - -- **The objective is mobile-first, responsive design**. Styled Breakpoints aims to apply the essential styles required for a layout to function at the smallest breakpoint. Additional styles are then added to adjust the design for larger devices. This approach optimizes your CSS, enhances rendering speed, and delivers an excellent user experience. - -
- -## Available breakpoints - -Styled Breakpoints includes six default breakpoints, often referred to as grid tiers, for building responsive designs. These breakpoints can be [customized](#customization). - -Each breakpoint has been carefully selected to accommodate containers with widths that are multiples of 12. The breakpoints also represent a subset of common device sizes and viewport dimensions, although they do not specifically target every use case or device. Instead, they provide a robust and consistent foundation for building designs that cater to nearly any device. - -```tsx -const breakpoints = { - xs: '0px', - sm: '576px', - md: '768px', - lg: '992px', - xl: '1200px', - xxl: '1400px', -}; -``` - -
+
## Media queries @@ -513,7 +513,7 @@ const SomeComponent = () => { ## Customization -### Strict Typed Breakpoints +

Strict Typed Breakpoints

 `app.tsx` @@ -549,7 +549,7 @@ const App = () => ( ); ``` -

πŸ’… Styled Components

 +

πŸ’… Styled Components

 `styled.d.ts` @@ -562,9 +562,9 @@ declare module 'styled-components' { } ``` -
+
-

πŸ‘©‍🎀 Emotion

 +

πŸ‘©‍🎀 Emotion

 `emotion.d.ts` @@ -577,9 +577,10 @@ declare module '@emotion/react' { } ``` +
-### Merge with another theme +

Merge with another theme

 `app.tsx` @@ -608,9 +609,9 @@ const App = () => ( ); ``` -

πŸ’… Styled Components

 +

πŸ’… Styled Components

 -Create file `styled.d.ts` +`styled.d.ts` ```ts import 'styled-components'; @@ -624,9 +625,9 @@ declare module 'styled-components' { } ``` -
+
-

πŸ‘©‍🎀 Emotion

 +

πŸ‘©‍🎀 Emotion

 `emotion.d.ts` @@ -642,6 +643,8 @@ declare module '@emotion/react' { } ``` +
+
## License diff --git a/docs/v11.x.x-README.md b/docs/v11.x.x-README.md deleted file mode 100644 index 6cf9a094..00000000 --- a/docs/v11.x.x-README.md +++ /dev/null @@ -1,425 +0,0 @@ -
-

- -
-styled-breakpoints
- - -GitHub Workflow Status - - - -coverage status - - - -npm bundle size - - - npm downloads - - -npm version - -

- -

Simple and powerful tool for creating media queries with

- -

- - styled-components - -     OR    -emotion - -

- -

- -## Core concepts - -**Breakpoints are the building blocks of responsive design**. Use them to control when your layout can be adapted at a particular viewport or device size. - -**Use media queries to architect your CSS by breakpoint**. Media queries are a feature of CSS that allow you to conditionally apply styles based on a set of browser and operating system parameters. We most commonly use min-width in our media queries. - -**Mobile first, responsive design is the goal**. Styled Breakpoints aims to apply the bare minimum of styles to make a layout work at the smallest breakpoint, and then layers on styles to adjust that design for larger devices. This optimizes your CSS, improves rendering time, and provides a great experience for your visitors. - -## Documentation - -Examples - -- [mobile first](#mobile-first) -- [desktop first](#desktop-first) -- [hooks api](#hooks-api) - -Getting Started - -- [Installation](#installation) -- [default breakpoints](#default-breakpoints) -- [customization](#customization) -- [object notation](#object-notation) - -API - -- [up](#up) -- [down](#down) -- [between](#between) -- [only](#only) -- [useBreakpoint](#useBreakpoint) - -## Examples - -### Mobile First - -From smallest to largest - - -Edit mobile-first - - -### Desktop First - -From largest to smallest - - - Edit desktop first example - - -### Hooks API - -#### Styled Components - - - Hooks api (styled-components) - - -#### Emotion - - -Hooks api (Emotion) - - -### Installation - -```sh -npm install styled-breakpoints - -# or - -yarn add styled-breakpoints - -# or - -pnpm add styled-breakpoints -``` - -### Available breakpoints - -Styled Breakpoints includes six default breakpoints, sometimes referred to as grid tiers, for building responsively. These breakpoints can be customized. Each breakpoint was chosen to comfortably hold containers whose widths are multiples of 12. Breakpoints are also representative of a subset of common device sizes and viewport dimensions they don’t specifically target every use case or device. Instead, the ranges provide a strong and consistent foundation to build on for nearly any device. - -```js -const defaultBreakpoints = { - xs: '0px', - sm: '576px', - md: '768px', - lg: '992px', - xl: '1200px', - xxl: '1400px', -}; -``` - -```js -import { up, down, between, only } from 'styled-breakpoints'; - -const Component = styled.div` - color: black; - - ${only('md')} { - color: rebeccapurple; - } -`; -``` - -### Customization - -```jsx -import { up, down, between, only, createTheme } from 'styled-breakpoints'; - -const theme = createTheme({ - sm: '576px', - md: '768px', - lg: '992px', - xl: '1200px', -}); - -const Component = styled.div` - color: black; - - ${only('sm')} { - color: rebeccapurple; - } - - ${between('sm', 'md')} { - color: hotpink; - } - - ${down('lg')} { - color: lightcoral; - } - - ${up('xl')} { - color: hotpink; - } -`; - - - This is cool! -; -``` - -### Object notation - -Make sure to explicitly pass `props` to breakpoint -methods. Please see the example below using default configuration: - -```js -import { down, between } from 'styled-breakpoints'; - -const Component = styled('div')((props) => ({ - color: 'black', - [down('md')(props)]: { - color: 'lightcoral', - }, - [between('sm', 'md')(props)]: { - color: 'hotpink', - }, -})); -``` - -### Hooks API - -#### Styled Components - -```jsx -import { useBreakpoint } from 'styled-breakpoints/react-styled'; -``` - -#### Emotion - -```jsx -import { useBreakpoint } from 'styled-breakpoints/react-emotion'; -``` - -
-
- -## API - -Core API is inspired by [Bootstrap responsive breakpoints](https://getbootstrap.com/docs/5.0/layout/breakpoints/). - -For example, let's take default values of breakpoints. - -### up - -
Type declaration - -```ts - declare function up( - min: string, - orientation?: 'portrait' | 'landscape' - ) => any -``` - -
- -```jsx -css` - ${up('md')} { - background-color: rebeccapurple; - } -`; -``` - -
Convert to pure css: - -```css -@media (min-width: 768px) { - background-color: rebeccapurple; -} -``` - -
- -### down - -
Type declaration - -```ts - declare function down( - max: string, - orientation?: 'portrait' | 'landscape' - ) => any -``` - -
- -We occasionally use media queries that go in the other direction (the given screen size or smaller). - -This function takes this declared breakpoint, subtracts 0.02px from it, and uses it as the maximum width value. - -```tsx -css` - ${down('md')} { - background-color: rebeccapurple; - } -`; -``` - -
Convert to: - -```css -@media (max-width: 767.98px) { - background-color: rebeccapurple; -} -``` - -
- -
- -> Why subtract .02px? Browsers don’t currently support [range context queries](https://www.w3.org/TR/mediaqueries-4/#range-context), so we work around the limitations of [min- and max- prefixes](https://www.w3.org/TR/mediaqueries-4/#mq-min-max) and viewports with fractional widths (which can occur under certain conditions on high-dpi devices, for instance) by using values with higher precision. - -
- -### between - -
Type declaration - -```ts - declare function between( - min: string, - max: string, - orientation?: 'portrait' | 'landscape' - ) => any -``` - -
- -Similarly, media queries may span multiple breakpoint widths: - -```js -css` - ${between('md', 'xl')} { - background-color: rebeccapurple; - } -`; -``` - -
Convert to: - -```css -@media (min-width: 768px) and (max-width: 1199.98px) { - background-color: rebeccapurple; -} -``` - -
- -### only - -
Type declaration - -```ts - declare function only( - key: string, - orientation?: 'portrait' | 'landscape' - ) => any -``` - -
- -There is also function for targeting a single segment of screen sizes using the minimum and maximum breakpoint widths. - -```jsx -css` - ${only('md')} { - background-color: rebeccapurple; - } -`; -``` - -
Convert to: - -```css -@media (min-width: 768px) and (max-width: 991.98px) { - background-color: rebeccapurple; -} -``` - -
- -### useBreakpoint - -```js -/** - * @param {function} up | down | between | only - * - * @return {(boolean|null)} `true` if currently matching the given query, - * `false` if not, and `null` if unknown (such as - * during server-side rendering) - */ -useBreakpoint(up('md')) => boolean | null -``` - -## Other - -### License - -MIT License - -Copyright (c) 2018-2019 [Maxim Alyoshin](https://github.com/mg901). - -This project is licensed under the MIT License - see the [LICENSE](https://github.com/mg901/styled-breakpoints/blob/master/LICENCE) file for details. - -### Contributors - -Thanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)): - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Maxim
πŸ’» 🎨 πŸ“– πŸ’‘ πŸ€” πŸ“’
Abu Shamsutdinov
πŸ’» πŸ’‘ πŸ€” πŸ‘€ πŸ“’
Sergey Sova
πŸ’» πŸ’‘ πŸ€” πŸ‘€ πŸ“’
Jussi Kinnula
πŸ› πŸ’»
RafaΕ‚ Wyszomirski
πŸ“–
Adrian CelczyΕ„ski
πŸ› πŸ’»
Alexey Olefirenko
πŸ’» πŸ€”

samholmes
πŸ’» πŸ€”
Ontopic
πŸ€”
Ryan Bell
πŸ€”
Bart Nagel
πŸ› πŸ’» πŸ’‘ πŸ€”
Greg McKelvey
πŸ’»
Buck DeFore
πŸ€”
Pierre Burel
πŸ›

Konstantin
πŸ› πŸ’»
Pawel Kochanek
πŸ› πŸ’»
- - - - - - -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! - -``` - -``` diff --git a/styled-breakpoints/create-styled-breakpoints-theme/create-styled-breakpoints-theme.d.ts b/styled-breakpoints/create-styled-breakpoints-theme/create-styled-breakpoints-theme.d.ts index aa6f09f9..895a8f0b 100644 --- a/styled-breakpoints/create-styled-breakpoints-theme/create-styled-breakpoints-theme.d.ts +++ b/styled-breakpoints/create-styled-breakpoints-theme/create-styled-breakpoints-theme.d.ts @@ -1,30 +1,29 @@ -declare module 'styled-breakpoints' { - type Orientation = 'portrait' | 'landscape'; +export type Orientation = 'portrait' | 'landscape'; - type BreakpointKeys = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'; - type Min = BreakpointKeys; - type Max = Exclude; +type BreakpointKeys = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl'; +type Min = BreakpointKeys; - type Up = (min: Min, orientation?: Orientation) => string; - type Down = (max: Max, orientation?: Orientation) => string; - type Between = (min: Min, max: Max, orientation?: Orientation) => string; - type Only = (key: BreakpointKeys, orientation?: Orientation) => string; +type Max = Exclude; - interface Options { - breakpoints?: Record; - errorPrefix?: string; - } +type Up = (min: Min, orientation?: Orientation) => string; +type Down = (max: Max, orientation?: Orientation) => string; +type Between = (min: Min, max: Max, orientation?: Orientation) => string; +type Only = (key: BreakpointKeys, orientation?: Orientation) => string; - export interface MediaQueries { - up: (min: T, orientation?: Orientation) => string; - down: (max: U, orientation?: Orientation) => string; - between: (min: T, max: U, orientation?: Orientation) => string; - only: (key: T, orientation?: Orientation) => string; - } +interface Options { + breakpoints?: Record; + errorPrefix?: string; +} - export interface StyledBreakpointsTheme { - breakpoints: T; - } +export interface MediaQueries { + up: (min: T, orientation?: Orientation) => string; + down: (max: U, orientation?: Orientation) => string; + between: (min: T, max: U, orientation?: Orientation) => string; + only: (key: T, orientation?: Orientation) => string; +} - export function createStyledBreakpointsTheme(options?: Options): any; +export interface StyledBreakpointsTheme { + breakpoints: T; } + +export function createStyledBreakpointsTheme(options?: Options): any; diff --git a/styled-breakpoints/index.d.ts b/styled-breakpoints/index.d.ts index 92f324ea..752b22d2 100644 --- a/styled-breakpoints/index.d.ts +++ b/styled-breakpoints/index.d.ts @@ -1 +1,5 @@ -export * from './create-styled-breakpoints-theme/create-styled-breakpoints-theme'; +export { + createStyledBreakpointsTheme, + StyledBreakpointsTheme, + MediaQueries, +} from './create-styled-breakpoints-theme/create-styled-breakpoints-theme';