Skip to content

Commit 566ab4b

Browse files
committed
doc tweaks
1 parent eec425f commit 566ab4b

File tree

8 files changed

+51
-100
lines changed

8 files changed

+51
-100
lines changed

README.md

Lines changed: 33 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,22 @@
1212

1313
![SauceLabsTestMatrix](https://app.saucelabs.com/browser-matrix/TheC0d3r.svg)
1414

15-
A PostCSS plugin and Javascript runtime combination, which allows you to write
16-
**container queries** in your CSS the same way you would write **media queries**.
15+
> A PostCSS plugin and Javascript runtime combination, which allows you to write
16+
> **container queries** in your CSS the same way you would write **media queries**.
1717
18-
🕶 **Resize Observer**: Uses the native ResizeObserver implentation when available,
18+
🕶 **Uses Resize Observer**: Uses the native ResizeObserver implentation when available,
1919
and falls back to a [polyfill](https://github.com/que-etc/resize-observer-polyfill)
2020
to detect size changes. If you use Chrome, [you can test](https://codesandbox.io/s/l3rmm1rz2l)
2121
how performant the plugin is with the native implementation. (Shipped in v64.)
2222

2323
📦 **Bundler Support**: Built with bundlers in mind, like [Parcel](https://parceljs.org),
24-
[webpack](https://webpack.js.org), [Browserify](http://browserify.org/) among others.
24+
[webpack](https://webpack.js.org) and [Browserify](http://browserify.org/).
2525

2626
🎲 **Component Support**: Built with component-based libraries in mind, like
27-
[React](https://reactjs.org), [Vue](https://vuejs.org/), [Ember](https://emberjs.com/),
28-
[Angular](https://angularjs.org/) among others.
27+
[React](https://reactjs.org), [Vue](https://vuejs.org/), [Ember](https://emberjs.com/)
28+
and [Angular](https://angularjs.org/).
2929

30-
📄 **Intuitive syntax**: Uses at-rules, the same way @media queries are:
30+
📄 **Intuitive Syntax**: Uses at-rules, the [same way @media queries do](docs/syntax.md#Queries):
3131
`@container (...) { ... }`
3232

3333
🎉 **Container Units**: [rh, rw, rmin, rmax,](docs/syntax.md#Units) which are
@@ -55,73 +55,20 @@ or "**Blocks**" ([BEM](http://getbem.com/naming/)).
5555

5656
## Demos
5757

58-
The best way to understand the concept, if you play around with it yourself.
58+
The best way to understand the concept, is if you try it for yourself.
5959

60-
- [Nested components](https://codesandbox.io/s/k9n28rkkl7)
60+
- [Nested Components](https://codesandbox.io/s/k9n28rkkl7)
6161
- [Social Posts](https://codesandbox.io/s/0l71yp80w)
6262
- [Without React](https://codesandbox.io/s/mo7nr90vmj)
6363

64-
Note that because these demos are hosted on [CodeSandbox](https://codesandbox.io)
65-
where webpack or PostCSS cannot (currently) be configured, styles are simply
66-
imported as strings and processed in the browser.
64+
Note that because these demos are hosted on [CodeSandbox](https://codesandbox.io),
65+
where webpack or PostCSS cannot ([currently](https://twitter.com/codesandbox/status/1087336337915760640))
66+
be configured, styles are simply imported as strings and processed in the browser.
6767
(Using [@zeecoder/cq-demo-utils](https://github.com/ZeeCoder/cq-demo-utils).)
6868

69-
While this works demo purposes, in a real application it is strongly recommended
70-
to process styles build-time, as later described in this documentation.
71-
72-
## Look and Feel
73-
74-
// todo remove once everything here is covered by other sections
75-
76-
```pcss
77-
// User.pcss
78-
.User {
79-
background: red;
80-
81-
@container (width >= 200px) and (height >= 200px) {
82-
background: green;
83-
}
84-
85-
&__name {
86-
font-size: 10rh;
87-
}
88-
89-
&__avatar {
90-
display: none;
91-
92-
@container (width >= 200px) and (height >= 200px) {
93-
display: block;
94-
}
95-
}
96-
}
97-
```
98-
99-
The above example assumes **webpack**, using **BEM** naming conventions and the
100-
**postcss-loader**.
101-
102-
`.User` is automatically detected to be the container (the first class in the
103-
proccessed file), and all following container queries / units will be related
104-
to the containing `.User` element.
105-
106-
The html then could look like this:
107-
108-
```html
109-
<div class="User">
110-
<div class="User__name"></div>
111-
<img class="User__avatar" src="..." />
112-
</div>
113-
```
114-
115-
(Note that for container queries and units to work, all elements must be
116-
descendants of the container, as their conditions and values only makes sense in
117-
a container's context.)
118-
119-
Finally, after you create a new `Container` instance, (passing in the container
120-
HTMLElement, and the extracted metadata) everything will just work.
121-
122-
_Note:_ A file can have multiple containers, with the [@define-container](docs/multiple-containers.md)
123-
declaration, but it's encouraged to have a dedicated file for each component.
124-
(Which is also the assumption of the [@zeecoder/react-container-query](https://github.com/ZeeCoder/container-query/tree/master/packages/react-container-query) package).
69+
While this works for demo purposes, in a real application it is strongly
70+
recommended to process styles build-time, as later described in this
71+
documentation.
12572

12673
## Documentation
12774

@@ -139,10 +86,19 @@ declaration, but it's encouraged to have a dedicated file for each component.
13986
- [Caveats](docs/caveats.md)
14087
- [CSS-in-JS](docs/css-in-js.md)
14188

89+
## What's Next?
90+
91+
[Ideas for Enhancement](https://goo.gl/7XtjDe)
92+
93+
## Support
94+
95+
Please consider supporting me if you like what I do on my
96+
[Patreon](https://www.patreon.com/zeecoder) page.
97+
14298
## Thoughts on Design
14399

144100
In case you're wondering about the tool's design, here is a list of goals I had
145-
in mind when I started:
101+
in mind with the initial implementation:
146102

147103
- Should be tested,
148104
- Should use containers instead of elements (As opposed to other "element-query"
@@ -155,21 +111,6 @@ in mind when I started:
155111
Browserify, etc.) and with Component-oriented UI libraries (React, Vue, etc.),
156112
- Should work best with component naming methodologies, like BEM or SUIT, but
157113
should also work without them.
158-
- Should work with CSS Modules.
159-
160-
## Next Up
161-
162-
[Ideas for Enhancement](https://goo.gl/7XtjDe)
163-
164-
## Alternatives
165-
166-
If you like the idea of container queries, but are not particularly
167-
convinced by this solution, then I encourage you to look at these alternatives:
168-
169-
- [EQCSS](https://github.com/eqcss/eqcss)
170-
- [CQ Prolyfill](https://github.com/ausi/cq-prolyfill)
171-
- [React Container Query](https://github.com/d6u/react-container-query)
172-
- [CSS Element Queries](https://github.com/marcj/css-element-queries)
173114

174115
## WICG
175116

@@ -188,10 +129,15 @@ the following links, where the disussions are happening:
188129
- [@zeecoder/react-resize-observer](https://github.com/ZeeCoder/react-resize-observer)
189130
- [use-resize-observer](https://github.com/ZeeCoder/use-resize-observer)
190131

191-
## Support
132+
## Alternatives
192133

193-
Please consider supporting me if you like what I do on my
194-
[Patreon](https://www.patreon.com/zeecoder) page.
134+
If you like the idea of container queries, but are not particularly
135+
convinced by this solution, then I encourage you to look at these alternatives:
136+
137+
- [EQCSS](https://github.com/eqcss/eqcss)
138+
- [CQ Prolyfill](https://github.com/ausi/cq-prolyfill)
139+
- [React Container Query](https://github.com/d6u/react-container-query)
140+
- [CSS Element Queries](https://github.com/marcj/css-element-queries)
195141

196142
## Big Thanks
197143

docs/getting-started.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,13 @@ Depending on your setup this file could contain more than one container's data.
1414
Once you have your metadata, all you need to do is to feed it to the Container
1515
instance, and it will take care of the rest!
1616

17-
Your job is even easier in React, as the Container instantiation is abstracted
18-
away.
17+
Your job is even easier in React, as Container instantiation is abstracted away.
18+
19+
**One important note on containers:**
20+
21+
For container queries and units to work, all elements using container queries
22+
must be descendants of a container, as their conditions and values only makes
23+
sense in a container's context.)
1924

2025
---
2126

docs/gulp.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,8 @@ gulp.task("styles", () =>
5858
```
5959

6060
The above CSS can include multiple containers thanks to `singleContainer: false`,
61-
using @define-container declarations.
61+
using @define-container declarations, as it's explained in the [Multiple Containers](multiple-containers.md)
62+
section.
6263

6364
---
6465

docs/multiple-containers.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Multiple Containers
22

3-
Instead of processing each container individually (on css file for each component
3+
Instead of processing each container individually (one CSS file for each component
44
for example), you might want to import all styles containing multiple container
55
declarations in a single file, and process that.
66

@@ -10,9 +10,8 @@ allow for the `@define-container;` declaration instead.
1010

1111
With that, you'll be able to declare multiple containers in a single file.
1212

13-
This is as simple as setting the `singleContainer` option to false.
14-
15-
(Showcased in the [Gulp](gulp.md)) section.)
13+
This is as simple as setting the `singleContainer` option to false, which was
14+
showcased in the [Gulp](gulp.md)) section.
1615

1716
### Example
1817

docs/parcel.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ npm install postcss-nested \
1717
@zeecoder/postcss-container-query --save-dev
1818
```
1919

20-
## Setup PostCSS
20+
## Setting up PostCSS
2121

2222
Add the following to a file named `.postcssrc` in your root directory.
2323

docs/react.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ You might have the following CSS:
4242
}
4343
```
4444

45-
### `<ContainerQuery>`
45+
### <ContainerQuery> with (children) Render Prop
4646

4747
Using render props.
4848

@@ -75,7 +75,7 @@ const App = () => (
7575
<ContainerQuery meta={meta} className="App">
7676
{size => (
7777
<div className="App__child">
78-
The App's size is: {size.width}x{size.height}
78+
Size: {size.width}x{size.height}
7979
</div>
8080
)}
8181
</ContainerQuery>
@@ -84,7 +84,7 @@ const App = () => (
8484
export default App;
8585
```
8686

87-
### `withContainerQuery`
87+
### withContainerQuery Higher-Order Component
8888

8989
If you prefer Higher-Order Components:
9090

docs/webpack.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ npm install postcss-loader \
1414
@zeecoder/postcss-container-query --save-dev
1515
```
1616

17-
## Setup PostCSS
17+
## Setting up PostCSS
1818

1919
Add the following to a file named `.postcssrc` in your root directory.
2020

docs/without-react.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Without React
22

33
Even though the library was made with webpack and React in mind, there's no
4-
reason why other bundlers or ui libraries wouldn't work.
4+
reason why other bundlers or UI libraries wouldn't work.
55

66
## Installation
77

0 commit comments

Comments
 (0)