Plugin links to external polyfill packages

[dpschen]

Kind of a follow up of #860

If I'm not mistaken I found out another issue that made it harder for me to use the focus-within-pseudo-class polyfill properly:

postcss-focus-within

Actual Description in READMEs

In the postcss-preset-env packages README.md under

Plugins list > Plugins that need client library > focus-within-pseudo-class

• Library links to https://github.com/jsxtools/focus-within and
• Polyfill links to https://github.com/jsxtools/focus-within/blob/master/README-BROWSER.md.

Expected description in READMEs

A) I think those links should probably be replaced with a reference to

https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-focus-within#browser

Since postcss-focus-within/src/browser.js contains already a polyfill, correct?

OR if I understood this wrong

B) The links from Library and Polyfill should be referenced at the top of the README of postcss-focus-within in a similar way that the README of postcss-focus-visible mentions its polyfill:

PostCSS Focus Visible lets you use the :focus-visible pseudo-class in CSS, following the Selectors Level 4 specification.

It is the companion to the focus-visible polyfill. Note that this plugin alone is not sufficient to polyfill for :focus-visible and that you need the browser's polyfill as well.

postcss-focus-visible

Actual Description in READMEs

In the quote the last paragraph browsers's polyfill confused me as well. Does this refer to:

• some kind of browser part of the csstool/postcss-plugin that I always need in order to get the postcss plugin running

OR

• some additional external polyfill package to make the support work, like it's the case with plugins/postcss-focus-visible and WICG/focus-visible.

Expected description in READMEs

If the answer is the first point maybe the description could be improved similar to:

It is the companion to the WICG/focus-visible polyfill. So you need to install WICG/focus-visible, because this plugin alone is not sufficient to polyfill for :focus-visible.

[romainmenke]

I think we moved the browser polyfill from https://github.com/jsxtools/focus-within to this repo.

I will try to go over all these links to make sure no old bits remain.

---

The underlying issue here is that these features require two parts :

• a PostCSS plugin
• a client side javascript library

One is a plugin, the other a polyfill.
But many consider all the PostCSS plugins to be polyfills for CSS.

Terms which can be misunderstood :

• polyfill
• plugin
• library
• browser polyfill (CSS runs in a browser, so postcss-preset-env is a polyfill for browsers right? :) )

In the past we have focussed on trying to find the right wording to explain this better.
But maybe it is clearer to do something different.

To use feature X in browsers Y you need to do both of these things :

• add PostCSS plugin foo to your PostCSS config
• add JavaScript file bar to each page of your website

By specifically mentioning that a user needs to do both steps we already prepare everyone for a bit of extra complexity.

From there we can elaborate and list all the steps very explicitly for both the PostCSS plugin and the JavaScript file intended to run client side.

[romainmenke]

I've already checked every link in the general readme for postcss-preset-env and made some edits.

Any ideas or feedback on how we can improve the documentation of these client side polyfills are welcome :)

[romainmenke]

@dpschen We've made some edits which we hope fully resolve this issue.
Thank you again for the feedback.