From 727f647f0ed56d5f908656a24529bd8da554c4b7 Mon Sep 17 00:00:00 2001 From: mg901 Date: Tue, 5 Mar 2024 03:47:37 +0300 Subject: [PATCH] =?UTF-8?q?feat:=20=F0=9F=8E=B8=20improve=20type=20inferen?= =?UTF-8?q?ce=20for=20orientation=20(#1803)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(readme): structural reorganization * docs(readme): add emoji * docs(readme): add section dividers * docs(readme): add more emoji * docs(readme): add a link to Emotion * docs(readme): change description for using with styled components and emotion * docs(readme): remove the emoji for the customization header * docs(readme): add `Integration to App` header * docs(readme): add a space before heading * feat: 🎸 improve type inference for orientation --- README.md | 247 ++++++++---------- .../index.d.ts | 10 +- 2 files changed, 117 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index 64927206..7a8f0ee2 100644 --- a/README.md +++ b/README.md @@ -31,23 +31,17 @@ styled-breakpoints
Styled Components Logo     OR    -Emotion logo +Emotion logo -

+



-# Breakpoints - -Breakpoints serve as adjustable widths that determine the behavior of your responsive layout across different device or viewport sizes. - -
- -## Preview +## 🌼 Preview -For **own** components. +**Inside** components. ```tsx const Box = styled.div` @@ -65,14 +59,14 @@ const Box = styled.div`
-For **third party** components. +**Outside** components. ```tsx import { useTheme } from 'styled-components'; // or '@emotion/react' const Layout = () => { - // You could use hooks API - const isMd = useMediaQuery(useTheme().breakpoints.up('md')); + const { breakpoints } = useTheme(); + const isMd = useMediaQuery(breakpoints.up('md')); return <>{isMd && }; }; @@ -82,7 +76,7 @@ const Layout = () => { ## Examples -### Mobile First +### 👉🏻 Mobile First From smallest to largest @@ -94,7 +88,7 @@ From smallest to largest
-### Desktop First +### 👉🏻 Desktop First From largest to smallest @@ -106,7 +100,7 @@ From largest to smallest
-### Hooks API +### 👉🏻 Hooks API

@@ -118,11 +112,10 @@ From largest to smallest
-## Documentation +## 📖 Documentation -- core concepts -- available breakpoints -- [quick start](#quick-start) +- [core concepts](#core-concepts) +- 🚩 [getting started](#getting-started) - [Media Queries API](#media-queries-api) - [min-width - up](#min-width---up) @@ -135,7 +128,7 @@ From largest to smallest
-

Core concepts

 +## 🧐 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. @@ -143,14 +136,32 @@ From largest to smallest - **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. -
+
+ +## Getting Started -

Available breakpoints

 +### 🚩 Installation + +```sh +npm install styled-breakpoints@latest + +# or + +yarn add styled-breakpoints@latest +``` + +
+ +### Configuration + +#### 🚩 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', @@ -162,35 +173,79 @@ const breakpoints = { }; ``` -
+
-## Quick start +`theme/config.ts` -

💅 Styled Components

 +```tsx +import { createStyledBreakpointsTheme } from 'styled-breakpoints'; -#### Installation +export const theme = createStyledBreakpointsTheme(); +``` -```sh -npm install styled-components styled-breakpoints@latest +
+
-# or +#### Customization + +##### 🚩 Breakpoints + +`theme/config.ts` + +```tsx +import { createStyledBreakpointsTheme } from 'styled-breakpoints'; -yarn add styled-components styled-breakpoints@latest +export const theme = createStyledBreakpointsTheme({ + breakpoints: { + small: '100px', + medium: '200px', + large: '300px', + xLarge: '400px', + xxLarge: '500px', + }, +}); ``` -
+
-#### Configuration +##### 🎨 Merge with Another Theme `theme/config.ts` ```tsx import { createStyledBreakpointsTheme } from 'styled-breakpoints'; -export const theme = createStyledBreakpointsTheme(); +export const primaryTheme = { + fonts: ['sans-serif', 'Roboto'], + fontSizes: { + small: '1em', + medium: '2em', + large: '3em', + }, +} as const; + +export const theme = { + ...primaryTheme, + ...createStyledBreakpointsTheme(), +}; ``` -
+
+
+ +

💅 Using with Styled Components

+ +##### 🚩 Installation + +```sh +npm install styled-components + +# or + +yarn add styled-components +``` + +
`theme/styled.d.ts` @@ -205,55 +260,23 @@ declare module 'styled-components' { } ``` -
- -`app.tsx` - -```tsx -import styled { ThemeProvider } from 'styled-components'; -import { theme } from './theme/config'; - -const Box = styled.div` - display: none; - - ${({ theme }) => theme.breakpoints.up('sm')} { - display: block; - } -`; - -const App = () => ( - - - -); -``` -
-

+
+
+ +

👩‍🎤 -Emotion

 +Using with Emotion -#### Installation +##### 🚩 Installation ```sh -npm install @emotion/{styled,react} styled-breakpoints@latest +npm install @emotion/{styled,react} # or -yarn add @emotion/{styled,react} styled-breakpoints@latest -``` - -
- -#### Configuration - -`theme/config.ts` - -```tsx -import { createStyledBreakpointsTheme } from 'styled-breakpoints'; - -export const theme = createStyledBreakpointsTheme(); +yarn add @emotion/{styled,react} ```
@@ -271,12 +294,17 @@ declare module '@emotion/react' { } ``` -
+
+
+ +### 🚀 Integration to App + +
`app.tsx` ```tsx -import styled, { ThemeProvider } from '@emotion/styled'; +import styled { ThemeProvider } from 'styled-components'; // or '@emotion/react' import { theme } from './theme/config'; const Box = styled.div` @@ -289,7 +317,7 @@ const Box = styled.div` const App = () => ( - + 🥳 ); ``` @@ -300,7 +328,7 @@ const App = () => ( ## Media queries API -- 🚀 Caching is implemented in all functions to optimize performance. +🚀 Caching is implemented in all functions to optimize performance.
@@ -330,7 +358,7 @@ const Box = styled.div` ```
-
Will be converted to pure css: +Will be converted to pure css: ```css @media (min-width: 768px) { @@ -370,7 +398,7 @@ const Box = styled.div` ```
-
Will be converted to pure css: +Will be converted to pure css: ```css @media (max-width: 767.98px) { @@ -415,7 +443,7 @@ const Box = styled.div` ```
-
Will be converted to pure css: +Will be converted to pure css: ```css @media (min-width: 768px) and (max-width: 991.98px) { @@ -456,7 +484,7 @@ const Box = styled.div` ```
-
Will be converted to pure css: +Will be converted to pure css: ```css @media (min-width: 768px) and (max-width: 1199.98px) { @@ -468,62 +496,12 @@ const Box = styled.div`

-## Customization - -

🛠️ Custom breakpoints

- -
- -`theme/config.ts` - -```tsx -import { createStyledBreakpointsTheme } from 'styled-breakpoints'; - -export const theme = createStyledBreakpointsTheme({ - breakpoints: { - small: '100px', - medium: '200px', - large: '300px', - xLarge: '400px', - xxLarge: '500px', - }, -}); -``` - -
- -

🎨 Merge with Another Theme

- -
- -`theme/config.ts` - -```tsx -import { createStyledBreakpointsTheme } from 'styled-breakpoints'; - -export const primaryTheme = { - fonts: ['sans-serif', 'Roboto'], - fontSizes: { - small: '1em', - medium: '2em', - large: '3em', - }, -} as const; - -export const theme = { - ...primaryTheme, - ...createStyledBreakpointsTheme(), -}; -``` - -
- ## `useMediaQuery` hook features: - 🧐 optimal performance by dynamically monitoring document changes in media queries. -- ⚙️ It supports SSR (server-side rendering). +- 💪🏻 It supports SSR (server-side rendering). - 📦 Minified and gzipped size 284b.
@@ -549,6 +527,7 @@ const SomeComponent = () => { }; ``` +

## License diff --git a/styled-breakpoints/create-styled-breakpoints-theme/index.d.ts b/styled-breakpoints/create-styled-breakpoints-theme/index.d.ts index 5448c55d..486be79c 100644 --- a/styled-breakpoints/create-styled-breakpoints-theme/index.d.ts +++ b/styled-breakpoints/create-styled-breakpoints-theme/index.d.ts @@ -40,8 +40,6 @@ export type OmitFirstInUnion = HeadlessTuple>[number]; export type Breakpoints = Record; export type ErrorPrefix = `[${string}]: `; -export type Orientation = 'portrait' | 'landscape'; - declare const DEFAULT_BREAKPOINTS: { readonly xs: '0px'; readonly sm: '576px'; @@ -61,10 +59,10 @@ export type Options = { interface StyledBreakpointsTheme { breakpoints: { - up(min: Min, orientation?: Orientation): string; - down(max: Max, orientation?: Orientation): string; - between(min: Min, max: Max, orientation?: Orientation): string; - only(key: Min, orientation?: Orientation): string; + up(min: Min, orientation?: 'portrait' | 'landscape'): string; + down(max: Max, orientation?: 'portrait' | 'landscape'): string; + between(min: Min, max: Max, orientation?: 'portrait' | 'landscape'): string; + only(key: Min, orientation?: 'portrait' | 'landscape'): string; }; }