[pigment-css][react] Add a How Pigment CSS works guide #41683

brijeshb42 · 2024-03-27T12:56:30Z

I have followed (at least) the PR section of the contributing guide.

mui-bot · 2024-03-27T12:59:15Z

Netlify deploy preview

https://deploy-preview-41683--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 68cacd0

siriwatknp

👍 very useful.

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

siriwatknp · 2024-03-28T04:39:11Z

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

+If the same was done using the `styled` call instead of `css` for the source:
+
+```js
+// app.js
+import { styled } from '@pigment-css/react';
+
+const Paragraph = styled.p(({ theme }) => ({
+  lineHeight: '1.4375em',
+  padding: 0,
+  position: 'relative',
+  color: (theme.vars || theme).palette.text.secondary,
+  ...theme.typography.body1,
+}));
+```
+
+The transformed output would look like:
+
+```js
+// app.js
+import { styled } from '@pigment-css/react';
+
+const Paragraph = styled('p')({
+  baseClasses: ['c1aiqtje'],
+});
+```
+
+You can notice above that now the runtime code, that finally ends up in the output bundle, doesn't involve any kind of CSS generation and it only needs to deal with primitive strings to apply it to the `p` that it'd render in the end.


I feel like this can be replaced with an ending for the css explanation. Maybe creating an example section for other processors would be better.

Like:

## Example transformation ### styled … ### keyframes ### generateAtomics

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

danilo-leal

I'll leave the more thorough writing review to Sam, but given this is the first branched-off page from the Pigment CSS docs, it rings as the call for a standalone doc space :) I've created a draft issue on the project for that, which we can talk about later! Either way, I appreciate we're explaining how the library works, and it'd be nice to really break down concepts such as the runtime vs. no-runtime scenario—maybe I can chime in here with some visual representation of them and others!

brijeshb42 · 2024-03-29T12:35:39Z

I was thinking of adding animations using Shiki to showcase the code-transforms. But since we are limited by plain markdown files, I didn't add it. It would be great if we are able to set-up Pigment CSS documentation within mui.com but using Pigment itself.

Screen.Recording.2024-03-29.at.6.07.17.PM.mov

danilo-leal · 2024-03-29T13:16:32Z

That looks so good! I'd definitely be interested to have this on the docs-infra stack, too!

samuelsycamore

Nice doc! I learned a lot by reading it :)

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

packages/pigment-css-react/README.md

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

danilo-leal

Looks great to me! (Would wait for Sam's final review, though)

samuelsycamore · 2024-04-05T13:00:16Z

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

+
+## Processor
+
+Pigment CSS uses the [WyW-in-JS](https://wyw-in-js.dev/) library that also powers [Linaria](https://linaria.dev/). It features a [processor](https://wyw-in-js.dev/how-to/custom-tagged-template#creating-a-processor) which makes it possible to create custom logic that's triggered by the presence of different imports from the library. The processor looks through the source code for `styled()`, `css()`, and other function calls and extracts the arguments to be evaluated. These evaluated values are then handed back to Pigment CSS for additional customization on top.


One final nitpick on style—I just realized that this is the only place where we refer to these functions as styled() and css(). Everywhere else we just write styled and css. Which one is your preference @brijeshb42 ? I like () since it makes it obvious that we're talking about functions, but I don't have a strong opinion either way.

Suggested change

Pigment CSS uses the [WyW-in-JS](https://wyw-in-js.dev/) library that also powers [Linaria](https://linaria.dev/). It features a [processor](https://wyw-in-js.dev/how-to/custom-tagged-template#creating-a-processor) which makes it possible to create custom logic that's triggered by the presence of different imports from the library. The processor looks through the source code for `styled()`, `css()`, and other function calls and extracts the arguments to be evaluated. These evaluated values are then handed back to Pigment CSS for additional customization on top.

Pigment CSS uses the [WyW-in-JS](https://wyw-in-js.dev/) library that also powers [Linaria](https://linaria.dev/). It features a [processor](https://wyw-in-js.dev/how-to/custom-tagged-template#creating-a-processor) which makes it possible to create custom logic that's triggered by the presence of different imports from the library. The processor looks through the source code for `styled`, `css`, and other function calls and extracts the arguments to be evaluated. These evaluated values are then handed back to Pigment CSS for additional customization on top.

There are two different types of references here. One is where we tell about the import of styled/css. In that case, it would be the same.
But in any other case, it would be a function call. So it should be styled()/css().

Ah ok that makes sense. Thanks for clarifying! Would you mind looking over the piece one last time to make sure we're referring to styled vs styled() and css vs css() accordingly? I didn't take that into account when I was editing before.

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Brijesh Bittu <brijeshb42@gmail.com>

brijeshb42 · 2024-04-16T12:03:56Z

@samuelsycamore I've applied all your suggestions. Could you +1 if there's nothing else?

samuelsycamore

let's fix the nbsp and then I think this is good to go 👍

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Brijesh Bittu <brijeshb42@gmail.com>

brijeshb42 requested review from mnajdova, siriwatknp, danilo-leal and samuelsycamore March 27, 2024 12:56

brijeshb42 added the package: pigment-css Specific to @pigment-css/* label Mar 27, 2024

danilo-leal added the docs Improvements or additions to the documentation label Mar 27, 2024

brijeshb42 force-pushed the pigment/how-it-works branch 2 times, most recently from e5caf4a to d6208be Compare March 27, 2024 13:03

Ehsansobhni approved these changes Mar 27, 2024

View reviewed changes

brijeshb42 changed the title ~~[pigment-css][react] Add a How Pigment works guide~~ [pigment-css][react] Add a How Pigment CSS works guide Mar 27, 2024

brijeshb42 force-pushed the pigment/how-it-works branch 2 times, most recently from b746b86 to f3992d0 Compare March 27, 2024 13:55

siriwatknp reviewed Mar 28, 2024

View reviewed changes

brijeshb42 force-pushed the pigment/how-it-works branch 5 times, most recently from c93df81 to 87e6977 Compare March 28, 2024 13:09

mnajdova reviewed Mar 28, 2024

View reviewed changes

danilo-leal reviewed Mar 28, 2024

View reviewed changes

samuelsycamore reviewed Mar 29, 2024

View reviewed changes

brijeshb42 force-pushed the pigment/how-it-works branch 2 times, most recently from 8697698 to 7637207 Compare March 30, 2024 05:57

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Apr 2, 2024

brijeshb42 force-pushed the pigment/how-it-works branch from 7637207 to ea98cc4 Compare April 2, 2024 12:42

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Apr 2, 2024

brijeshb42 force-pushed the pigment/how-it-works branch from 14f6692 to 64c9c9f Compare April 2, 2024 13:20

danilo-leal requested a review from samuelsycamore April 2, 2024 18:55

samuelsycamore reviewed Apr 3, 2024

View reviewed changes

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md Outdated Show resolved Hide resolved

brijeshb42 requested review from samuelsycamore and danilo-leal April 5, 2024 09:17

danilo-leal approved these changes Apr 5, 2024

View reviewed changes

samuelsycamore reviewed Apr 5, 2024

View reviewed changes

brijeshb42 added 3 commits April 8, 2024 16:21

[pigment-css][react] Add a How Pigment works guide

986bc46

Little more detail about processor

e5c9225

Update references to call vs imports

68cacd0

brijeshb42 force-pushed the pigment/how-it-works branch from 034d6fc to 68cacd0 Compare April 8, 2024 10:54

brijeshb42 requested a review from samuelsycamore April 8, 2024 14:39

samuelsycamore reviewed Apr 9, 2024

View reviewed changes

Apply suggestions from code review

a3b817c

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Brijesh Bittu <brijeshb42@gmail.com>

samuelsycamore approved these changes Apr 16, 2024

View reviewed changes

packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md Outdated Show resolved Hide resolved

Update packages/pigment-css-react/HOW_PIGMENT_CSS_WORKS.md

275224d

Co-authored-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Signed-off-by: Brijesh Bittu <brijeshb42@gmail.com>

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Apr 23, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[pigment-css][react] Add a How Pigment CSS works guide #41683

[pigment-css][react] Add a How Pigment CSS works guide #41683

brijeshb42 commented Mar 27, 2024

mui-bot commented Mar 27, 2024 •

edited

siriwatknp left a comment

siriwatknp Mar 28, 2024

danilo-leal left a comment •

edited

brijeshb42 commented Mar 29, 2024 •

edited

danilo-leal commented Mar 29, 2024

samuelsycamore left a comment

danilo-leal left a comment

samuelsycamore Apr 5, 2024

brijeshb42 Apr 5, 2024

samuelsycamore Apr 5, 2024

brijeshb42 Apr 8, 2024

brijeshb42 commented Apr 16, 2024

samuelsycamore left a comment


		## Processor

		Pigment CSS uses the [WyW-in-JS](https://wyw-in-js.dev/) library that also powers [Linaria](https://linaria.dev/). It features a [processor](https://wyw-in-js.dev/how-to/custom-tagged-template#creating-a-processor) which makes it possible to create custom logic that's triggered by the presence of different imports from the library. The processor looks through the source code for `styled()`, `css()`, and other function calls and extracts the arguments to be evaluated. These evaluated values are then handed back to Pigment CSS for additional customization on top.

[pigment-css][react] Add a How Pigment CSS works guide #41683

Are you sure you want to change the base?

[pigment-css][react] Add a How Pigment CSS works guide #41683

Conversation

brijeshb42 commented Mar 27, 2024

mui-bot commented Mar 27, 2024 • edited

Netlify deploy preview

Bundle size report

siriwatknp left a comment

Choose a reason for hiding this comment

siriwatknp Mar 28, 2024

Choose a reason for hiding this comment

danilo-leal left a comment • edited

Choose a reason for hiding this comment

brijeshb42 commented Mar 29, 2024 • edited

danilo-leal commented Mar 29, 2024

samuelsycamore left a comment

Choose a reason for hiding this comment

danilo-leal left a comment

Choose a reason for hiding this comment

samuelsycamore Apr 5, 2024

Choose a reason for hiding this comment

brijeshb42 Apr 5, 2024

Choose a reason for hiding this comment

samuelsycamore Apr 5, 2024

Choose a reason for hiding this comment

brijeshb42 Apr 8, 2024

Choose a reason for hiding this comment

brijeshb42 commented Apr 16, 2024

samuelsycamore left a comment

Choose a reason for hiding this comment

mui-bot commented Mar 27, 2024 •

edited

danilo-leal left a comment •

edited

brijeshb42 commented Mar 29, 2024 •

edited