From cf88f8e66bfad19280713c689d7aa508d8bd93a8 Mon Sep 17 00:00:00 2001 From: Romain Menke Date: Mon, 7 Nov 2022 19:29:17 +0100 Subject: [PATCH 1/3] psotcss-custom-media : improve docs --- plugins/postcss-custom-media/.tape.mjs | 9 +++ plugins/postcss-custom-media/README.md | 75 +++++++++++++++++++ plugins/postcss-custom-media/docs/README.md | 48 ++++++++++++ .../test/examples/complex.css | 6 ++ .../test/examples/complex.expect.css | 11 +++ .../test/examples/false.css | 5 ++ .../test/examples/false.expect.css | 3 + .../test/examples/true.css | 5 ++ .../test/examples/true.expect.css | 3 + 9 files changed, 165 insertions(+) create mode 100644 plugins/postcss-custom-media/test/examples/complex.css create mode 100644 plugins/postcss-custom-media/test/examples/complex.expect.css create mode 100644 plugins/postcss-custom-media/test/examples/false.css create mode 100644 plugins/postcss-custom-media/test/examples/false.expect.css create mode 100644 plugins/postcss-custom-media/test/examples/true.css create mode 100644 plugins/postcss-custom-media/test/examples/true.expect.css diff --git a/plugins/postcss-custom-media/.tape.mjs b/plugins/postcss-custom-media/.tape.mjs index 7dac6d271..3c91c6623 100644 --- a/plugins/postcss-custom-media/.tape.mjs +++ b/plugins/postcss-custom-media/.tape.mjs @@ -24,6 +24,15 @@ postcssTape(plugin)({ preserve: true } }, + 'examples/true': { + message: 'minimal example with "true"', + }, + 'examples/false': { + message: 'minimal example with "false"', + }, + 'examples/complex': { + message: 'minimal example complex queries', + }, 'nesting': { message: 'works when nested' }, diff --git a/plugins/postcss-custom-media/README.md b/plugins/postcss-custom-media/README.md index e847e2fba..1109e4cdd 100644 --- a/plugins/postcss-custom-media/README.md +++ b/plugins/postcss-custom-media/README.md @@ -18,6 +18,81 @@ } ``` +## `true` and `false` + +With `@custom-media` you can use the constants `true` and `false`. +These are especially handy when debugging. + +You are unsure how your page is affected when a certain media query matches or not you can use these to quickly toggle the results. +This plugin downgrades these queries to something that works in all browsers. + +Quickly check the result as if the query matches: + +```pcss +@custom-media --small-viewport true; + +@media (--small-viewport) { + /* styles for small viewport */ +} + +/* becomes */ + +@media (max-color:2147477350) { + /* styles for small viewport */ +} +``` + +Quickly check the result as if the query does not match: + +```pcss +@custom-media --small-viewport false; + +@media (--small-viewport) { + /* styles for small viewport */ +} + +/* becomes */ + +@media (color:2147477350) { + /* styles for small viewport */ +} +``` + +## logical evaluation of complex media queries + +It is impossible to accurately and correctly resolve complex `@custom-media` queries +as these depend on the browser the queries will eventually run in. + +_Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._ + +⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity. +GZIP works great to de-dupe this but a lot of complex media queries will have a performance impact. + +An example of a very complex (and artificial) use-case : + +```pcss + +@custom-media --a-complex-query tty and (min-width: 300px); + +@media not screen and ((not (--a-complex-query)) or (color)) { + /* Your CSS */ +} + +/* becomes */ + + +@media tty and (min-width: 300px) { +@media not screen and ((not (max-color:2147477350)) or (color)) { + /* Your CSS */ +} +} +@media not tty and (min-width: 300px) { +@media not screen and ((not (color:2147477350)) or (color)) { + /* Your CSS */ +} +} +``` + ## Usage Add [PostCSS Custom Media] to your project: diff --git a/plugins/postcss-custom-media/docs/README.md b/plugins/postcss-custom-media/docs/README.md index 6d3d8dc76..e22cd32f3 100644 --- a/plugins/postcss-custom-media/docs/README.md +++ b/plugins/postcss-custom-media/docs/README.md @@ -26,6 +26,54 @@ ``` +## `true` and `false` + +With `@custom-media` you can use the constants `true` and `false`. +These are especially handy when debugging. + +You are unsure how your page is affected when a certain media query matches or not you can use these to quickly toggle the results. +This plugin downgrades these queries to something that works in all browsers. + +Quickly check the result as if the query matches: + +```pcss + + +/* becomes */ + + +``` + +Quickly check the result as if the query does not match: + +```pcss + + +/* becomes */ + + +``` + +## logical evaluation of complex media queries + +It is impossible to accurately and correctly resolve complex `@custom-media` queries +as these depend on the browser the queries will eventually run in. + +_Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._ + +⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity. +GZIP works great to de-dupe this but a lot of complex media queries will have a performance impact. + +An example of a very complex (and artificial) use-case : + +```pcss + + +/* becomes */ + + +``` + diff --git a/plugins/postcss-custom-media/test/examples/complex.css b/plugins/postcss-custom-media/test/examples/complex.css new file mode 100644 index 000000000..5099b0f0e --- /dev/null +++ b/plugins/postcss-custom-media/test/examples/complex.css @@ -0,0 +1,6 @@ + +@custom-media --a-complex-query tty and (min-width: 300px); + +@media not screen and ((not (--a-complex-query)) or (color)) { + /* Your CSS */ +} diff --git a/plugins/postcss-custom-media/test/examples/complex.expect.css b/plugins/postcss-custom-media/test/examples/complex.expect.css new file mode 100644 index 000000000..f5563f551 --- /dev/null +++ b/plugins/postcss-custom-media/test/examples/complex.expect.css @@ -0,0 +1,11 @@ + +@media tty and (min-width: 300px) { +@media not screen and ((not (max-color:2147477350)) or (color)) { + /* Your CSS */ +} +} +@media not tty and (min-width: 300px) { +@media not screen and ((not (color:2147477350)) or (color)) { + /* Your CSS */ +} +} diff --git a/plugins/postcss-custom-media/test/examples/false.css b/plugins/postcss-custom-media/test/examples/false.css new file mode 100644 index 000000000..9957197fa --- /dev/null +++ b/plugins/postcss-custom-media/test/examples/false.css @@ -0,0 +1,5 @@ +@custom-media --small-viewport false; + +@media (--small-viewport) { + /* styles for small viewport */ +} diff --git a/plugins/postcss-custom-media/test/examples/false.expect.css b/plugins/postcss-custom-media/test/examples/false.expect.css new file mode 100644 index 000000000..81462295b --- /dev/null +++ b/plugins/postcss-custom-media/test/examples/false.expect.css @@ -0,0 +1,3 @@ +@media (color:2147477350) { + /* styles for small viewport */ +} diff --git a/plugins/postcss-custom-media/test/examples/true.css b/plugins/postcss-custom-media/test/examples/true.css new file mode 100644 index 000000000..825dff4d7 --- /dev/null +++ b/plugins/postcss-custom-media/test/examples/true.css @@ -0,0 +1,5 @@ +@custom-media --small-viewport true; + +@media (--small-viewport) { + /* styles for small viewport */ +} diff --git a/plugins/postcss-custom-media/test/examples/true.expect.css b/plugins/postcss-custom-media/test/examples/true.expect.css new file mode 100644 index 000000000..1fb198d97 --- /dev/null +++ b/plugins/postcss-custom-media/test/examples/true.expect.css @@ -0,0 +1,3 @@ +@media (max-color:2147477350) { + /* styles for small viewport */ +} From 0d246d498c493d341a00739481b3c8786d79bc6c Mon Sep 17 00:00:00 2001 From: Romain Menke Date: Mon, 7 Nov 2022 19:31:47 +0100 Subject: [PATCH 2/3] wording --- plugins/postcss-custom-media/README.md | 2 +- plugins/postcss-custom-media/docs/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/postcss-custom-media/README.md b/plugins/postcss-custom-media/README.md index 1109e4cdd..5ca9c095f 100644 --- a/plugins/postcss-custom-media/README.md +++ b/plugins/postcss-custom-media/README.md @@ -23,7 +23,7 @@ With `@custom-media` you can use the constants `true` and `false`. These are especially handy when debugging. -You are unsure how your page is affected when a certain media query matches or not you can use these to quickly toggle the results. +If you are unsure how your page is affected when a certain media query matches or not you can use these, to quickly toggle the results. This plugin downgrades these queries to something that works in all browsers. Quickly check the result as if the query matches: diff --git a/plugins/postcss-custom-media/docs/README.md b/plugins/postcss-custom-media/docs/README.md index e22cd32f3..921ab7b45 100644 --- a/plugins/postcss-custom-media/docs/README.md +++ b/plugins/postcss-custom-media/docs/README.md @@ -31,7 +31,7 @@ With `@custom-media` you can use the constants `true` and `false`. These are especially handy when debugging. -You are unsure how your page is affected when a certain media query matches or not you can use these to quickly toggle the results. +If you are unsure how your page is affected when a certain media query matches or not you can use these, to quickly toggle the results. This plugin downgrades these queries to something that works in all browsers. Quickly check the result as if the query matches: From c805d351e17fdff3c892fa523300ba3ef75db075 Mon Sep 17 00:00:00 2001 From: Romain Menke Date: Mon, 7 Nov 2022 19:33:18 +0100 Subject: [PATCH 3/3] wording --- plugins/postcss-custom-media/README.md | 4 ++-- plugins/postcss-custom-media/docs/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/postcss-custom-media/README.md b/plugins/postcss-custom-media/README.md index 5ca9c095f..8fc2e1bc4 100644 --- a/plugins/postcss-custom-media/README.md +++ b/plugins/postcss-custom-media/README.md @@ -65,8 +65,8 @@ as these depend on the browser the queries will eventually run in. _Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._ -⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity. -GZIP works great to de-dupe this but a lot of complex media queries will have a performance impact. +⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity.
+GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact. An example of a very complex (and artificial) use-case : diff --git a/plugins/postcss-custom-media/docs/README.md b/plugins/postcss-custom-media/docs/README.md index 921ab7b45..2c7cb995f 100644 --- a/plugins/postcss-custom-media/docs/README.md +++ b/plugins/postcss-custom-media/docs/README.md @@ -61,8 +61,8 @@ as these depend on the browser the queries will eventually run in. _Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._ -⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity. -GZIP works great to de-dupe this but a lot of complex media queries will have a performance impact. +⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity.
+GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact. An example of a very complex (and artificial) use-case :