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..8fc2e1bc4 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. + +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: + +```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 having 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..2c7cb995f 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. + +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: + +```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 having 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 */ +}