Aspnetcore.docs: [RC1] Blazor CSS isolation

[javiercn]

• Add *.razor.css files side by side to include scoped css styles.
• Use the ::deep token in your razor.css file to limit the applicability of the scope isolation so you can target markup defined by other components within your scope.
• Scoped styles are available under _framework/scoped.styles.css
• Document how automatic bundling can be disabled to use a separate third-party tool for post-processing the scoped css.
  
  
  
  • This area might receive small tweaks, so hold off on this.
  
  
• Document how to pre-process the css files if you are using another pre-processor like LESS or SASS.
  
  
  
  • This might undergo some tweaks too.
  
  

We'll be providing more content here before this is ready.

/cc: @SteveSandersonMS

[guardrex]

@javiercn I can take a stab 🔪 at this based on Steve's presentation on the Community Standup combined with the engineering issue(s)/PR(s). Do you want me to give it a shot? ... might take a little pressure off of u 💥🤯💥.

[javiercn]

If you want to, go for it, we are still working out some changes that will land on RC1

[guardrex]

In that case, I'll wait until RC1. I was burned 🤕 back when I tried to document Health Checks _too early_. I should have plenty of time after RC1 comes out.

Let's do this ... I'll take the assignment now, and we'll fix anything on review when I put the PR up after RC1 releases.

Same thing for Identity 2.0 updates. Immediately after RC1, I'll get busy on it. If I hit any problems, I'll ping on that issue. Otherwise, we can troubleshoot my PR after I put it up ... after RC1. Given that the changes might be extensive, it might take me a week (or longer if other work hits me). You can always track what I'm currently working on on the Blazor.Docs project by looking at the In Progress column.

[daveabrock]

Hey, all. I wanted to let you know I just got done writing a post on this feature. I appreciate the bulleted list on what to cover here, as it helped me make sure I was covering everything. 😎

As you're writing this, feel free to lean on that, correct me where I was wrong, and so on. Or, if you'd like me to take a stab at writing this for you guys, I'd be more than happy to give it a shot.

[guardrex]

@daveabrock You are _super welcome_ 🥇 to write the section on this, and we can put your name on the author byline with a link to your blog (or organization website).

Let me get back to you tomorrow (Friday) morning on where it will slot into the coverage and any notes/gotchas going in on it.

[daveabrock]

@guardrex Sounds good! I've done plenty of contributions but this would be my first Blazor one—so all ears on if there's any gotchas for writing Blazor docs.

[guardrex]

@javiercn, TL;DR on my guidance to @daveabrock below, _but_ ... you said that there might be additional updates to CSS isolation for RC1. Anything in that vein for @daveabrock since you opened this issue?

@daveabrock ... I read your post. Great piece. I hope you let @jongalloway know (if he doesn't get the ping here on https://daveabrock.com/2020/09/10/blazor-css-isolation) about that for a mention in a Community Standup. You can tweet him.

There's enough here that this should be a new topic in the Components node of the Blazor ToC. If Dan wants it elsewhere tho, no worries ... topic content is easy to move at the PR stage, of course. He'll let us know on the PR. For now, let's proceed with creating a new topic for this.

Two options ...

1. You fork+clone+branch the repo, create the topic with its metadata for the repo, and integrate the topic into the site's ToC. You submit the PR, and I'll make a direct edit pass on it. You can then pull down my changes and continue to work with it if needed.
2. You just write the topic and shoot it into an issue comment here, and I'll do the legwork on those other bits :point_up:. I'll submit the PR, and we can pick up with updates from there.

If you want the fully experience, then I'll supply some added notes here for Option 1. If you just want to go Option 2, then I'll just ping you on the PR for further discussion and updates after I've taken your issue comment into a repo doc. Let me know which way you want to go :ear:, and either way is fine. It just depends on how much into the doc repo weeds you want to get into it.

WRT the content itself, a few points ...

• This will be a reference topic, so it won't have the tutorial-ish language of your blog post. It's more like :smile: ...

  

  — _"All we want are the facts, ma'am."_ Sgt. Joe Friday (Jack Webb), Dragnet ©1949-59 NBCUniversal

  ... so just write in short, direct sentences. Keep paragraphs focused on each key point. These reference topics are less conversational and more like typewriter maintenance instructions. lol ... Well, perhaps not that bad. :smile:

• Tips ... and forgive me that I'm telling u things you already know. I'm just going to rattle off some common things that we need to address in content submissions ...

  • Try to avoid the pronoun "you." Opt for imperative sentences: "Open the file and ..." instead of "You open the file and ...".
  • Avoid future tense. Opt for "The command opens ..." instead of "The command will open ...".
  • No pics ... too hard to maintain.
  • In-text code snippets are ok at this stage. I'll move them to the common sample apps later. Code lines have a limit of 85 characters, so go ahead and feel free to break long code lines in ways that one wouldn't normally do in a real app. However, we do let command shell lines run over the 85 char limit so that they can be cut-'n-paste into command shells. It's just code lines that we do this for. It prevents horizontal scrollbars on many devices.
  • We're using a LOT of code fencing these days due to localization concerns. This includes file names, paths (URL and file system), and page names from template apps (e.g., the Counter page). The syntax for components is to code-fence the component name (e.g., the `Counter` component).
  • For API in-text, use single back-ticks. I'll drop in the API cross-links when I edit the PR. Same thing for cross-links to other docs ... just use the full URL. I'll touch them up if needed on my pass.
  • Use sentence casing for headers ("How to work with child components" over "How to Work with Child Components"), just like in your blog post. Avoid gerunds ("-ing" words) in the title and section headings ... they don't translate well. However, common industry terms are fine (e.g., "logging," "databinding," "caching," etc.).

• The title of this will be "ASP.NET Core Blazor CSS isolation" with a sidebar ToC entry of "CSS isolation" under the "Components" node.

• No prereqs needed for this because we'll version the whole topic for 5.0. I'll give more info if you go for Option 1 on the write-up.

• WRT LESS/SASS, I hope that we don't maintain one or more _explicit 3rd party CSS preprocessor code examples_. A section that describes the general approach, as your blog post does in the first two paragraphs of your section, is my recommendation with cross-links to the 3rd party tools. Let them doc their own tools. This is subject to Javier's and Artak's input with Dan's final call. For one thing, I think maintaining code for 3rd party is a PITA. I can barely keep up with our own code. 😅 Also, I have a long-running many years view that it's bad for the industry when big tech "picks winners" among 3rd party ... any tech company ... not just the Foundation or MS. It could stifle innovation and surely leads to the charge that big tech companies are monopolies in all the worst sense. Total imo there ... I've been consistent on that point and called it out in other contexts. Sometimes there's agreement on it, sometimes not. Anyway ... not my call. I leave it to DR to say what's best. I'm just recommending a course of action.

[javiercn]

@daveabrock that's a great post! It covers almost everything I would cover. There are a few things we've changed and that are important to reflect on the docs and a couple of additional details:

In the things that have changes:

• We now produce two separate bundles:
  
  
  
  • One for the "app" (the transitive closure of dependencies)
  
  
  • This is used when the "app" runs and is published.
  
  
  • The app bundle always appears at the root of the url space under "<>.styles.css" unless you change it by specifying a different <StaticWebAssetBasePath> property that is not the default, in that case that gets respected and appears at `<>/<
    
  • One for the "project" (it only bundles the things within your project).
  
  
  • This is used when the project is packaged as a nuget package or referenced as a Razor Class Library.
  
  
  • The project bundle always appears at <<StaticWebAssetsBasePath>>/<<project>>.lib.scp.css
  
  
  • We do this so that it is more natural to reference assets from your scoped CSS files that live in the wwwroot of your project/classlibrary.
  
  
  • We want to make sure that the app bundle by default appears in the same location for SSB and Blazor Wasm.
  
  
• The bundle we produce now contains imports to other bundles instead of producing a single bundle.
  
  
  
  • The reason is similar to the one defined above, we want to make sure you can reliably reference assets from your scoped css file, and the previous design that bundled everything together broke that, as changing the bundle location would affect those urls.
  
  

On the things that are missing or need more detail:

• Including the SASS piece is great, since we are bound to get questions about it:
  
  
  
  • We need to go into more detail about this, probably writing a sample Target that invokes the SASS compiler at the right time, probably it needs to run before "ResolveScopedCssInputs". It is fine if the
  
  
• The *.razor.css is our convention, but you can define your own if you like via MSBuild by writing an itemgroup path/to/razor/component/file
• You can define the identifiers to use for the scope of a given class. If you are building a package/library you can have the scoping rules be applied but choose a different set of identifiers, so you can integrate with other tooling and so on.
• If you want to use bundling with WebPack and similar, the bundle process needs to happen at a specific point in the build for it to work well with Blazor Webassembly PWAs.
  
  
  
  • This is because we need to compute integrity hashes to put into the PWA manifest. In general, doing so before Compile should be fine, but there might be a better place to do it. (That latter these things happen in the MSBuild pipeline the better, since that leaves more flexibility in the future to integrate other things).
  
  
• We don't support using your own @import within scoped css files, this is because we can't guarantee that those styles are isolated, and we can't define a sensible "import order" when we bundle things, so we need to ensure only scoped styles are bundled.
• We don't do magic to import your CSS, we just add a link href in your template, and that takes care of it. This is nice because the feature comes at 0 cost if you are not using it, the runtime knows nothing about it.

I think that covers everything, that said there are extensive comments on the feature PR as well as in the msbuild code file

[daveabrock]

Hey guys, thanks for the nice words on the post (and @guardrex, @jongalloway has come to expect a not-so-subtle nudge the morning of the standups 👌).

@guardrex, I'm fine with the first option. As I think I said (it's been a long week) I have experience with your process so that should save time for everybody. I know you are targeting RC1 for this—when is that, exactly? Thanks for the tips. I'll keep those in mind.

@javiercn, thanks for the great input! Are all these changes coming with RC1, or is it in preview 8? I was playing with the preview 8 bits, obviously. I would definitely prefer to get my hands on the bits before publishing this post, if possible.

As for some of the MSBuild settings in the project file, could someone assist on how to use DisableScopedCssBinding and StaticWebAssetBasePath in terms of how it fits in the structure of the project file (like the tag, what node it's under, and so on). I was trying to put some pieces together looking at the code, but would appreciate some assistance there.

[guardrex]

targeting RC1 for this—when is that, exactly?

I know the target date, but I don't like saying what it is. It might be public info, but I just don't like conveying dates without explicit authorization. Javier will let u know if he thinks this should absolutely be up for the RC1 release (that day) or not; and if so, he (or Dan) can convey the date, here or via email.

get my hands on the bits before publishing this post

This is what I was going to do, so there would've been a delay of at least a couple of days post RC1 release. I assume that they're fine with you taking that course as well.

[javiercn]

I don't remember exactly if they are in RC1 or RC2, I believe RC1, but Dan can confirm since he's played with the bits more recently.

As to how to put things in the project file:

<PropertyGroup>
  <StaticWebAssetBasePath>_content/$(PackageId)</StaticWebAssetBasePath>
  <DisableScopedCssBundling>true</DisableScopedCssBundling>
</PropertyGroup>

There's a lot of content in the comments https://github.com/dotnet/aspnetcore/blob/release/5.0-rc1/src/Razor/Microsoft.NET.Sdk.Razor/src/build/netstandard2.0/Microsoft.NET.Sdk.Razor.ScopedCss.targets and on the PRs with the details

[daveabrock]

Thanks @javiercn. I have what I need to get started.

And @guardrex, all fair on timing. I'm just looking for a general timeframe - do you want something in the next two weeks, four weeks, six weeks?

[guardrex]

:smile: ... Dan has publicly said 'target _in September_'. ⏰ ... soon ... very soon is fair to say if everything goes off without a hitch.

[isc30]

Hi everyone, should the docs also cover referencing a RCL that has components with scoped CSS?
At least reminding the net5.0 as a target and 5.0.0-preview.8.20414.8 as version for Microsoft.AspNetCore.Components NuGet packages.

[daveabrock]

:smile: ... Dan has publicly said 'target _in September_'. ⏰ ... soon ... very soon is fair to say if everything goes off without a hitch.

You don't say? 😀
https://devblogs.microsoft.com/dotnet/announcing-net-5-0-rc-1/

Will try to carve out some time this week.

[guardrex]

🎉

carve out some time this week

Me, too. I've a got a _SEA_ 🚢 of Blazor WASM security bits to update!

[daveabrock]

Hi everyone, should the docs also cover referencing a RCL that has components with scoped CSS?
At least reminding the net5.0 as a target and 5.0.0-preview.8.20414.8 as version for Microsoft.AspNetCore.Components NuGet packages.

Any thoughts, @javiercn?

[SteveSandersonMS]

@daveabrock We have project template for RCL which will be correctly set up to use scoped CSS by default, so hopefully that will put people on the right track. I'm not sure if we'll cover in the docs what versions of things are required, since typically the docs don't do that for each feature - the docs themselves are tied to an overall version of the framework.

[daveabrock]

Update for you, @guardrex: working with the RC1 bits and should have a PR for you tomorrow morning.

[guardrex]

Thanks @daveabrock ... no giant huge rush if you feel that you need more time ... we are in preview after all.

[daveabrock]

@guardrex - I would like an initial review but I have QUESTIONS! Would you like a link to the branch or should I just do a PR, knowing there will be a lot of back and forth?

[guardrex]

A link to your branch is fine. We can discuss it there.

btw--- My hours are almost burned for the week ... I have just a couple of hours left today, then I'm back on Monday morning. I suspect a discussion would bleed over to Monday. That's no big deal tho ... next week for this is fine. Everything for 5.0 is running very much on time 🚅 at the moment. 🤞🍀

[daveabrock]

A link to your branch is fine. We can discuss it there.

btw--- My hours are almost burned for the week ... I have just a couple of hours left today, then I'm back on Monday morning. I suspect a discussion would bleed over to Monday. That's no big deal tho ... next week for this is fine. Everything for 5.0 is running very much _on time_ 🚅 at the moment. 🤞🍀

Thanks for letting me know and I definitely anticipated a few days to think through everything.

Here's a link to my updates in the branch (I also updated toc.yaml so the nav is set to go):
https://github.com/daveabrock/AspNetCore.Docs/blob/daveabrock/css-isolation/aspnetcore/blazor/components/css-isolation.md

I welcome your feedback on content and tone.

My questions:

• I just added two paragraphs about preprocessor support. I go back and forth between what I have currently, and going in depth with an example concerning what order is required and whatnot. I know we don't want to endorse third-party tools this much but this is a very popular topic, considering the questions I'm getting from my post and whatnot.
• I looked at the build file, @javiercn, and couldn't see where this happens: "The *.razor.css is our convention, but you can define your own if you like via MSBuild by writing an itemgroup path/to/razor/component/file" ... so am looking for guidance there. In the doc, I have it added but the sample is stubbed out as FigureThisOut.
• I added a quick reference about the project bundle: should we go in-depth about how that works? An RCL example? It should "just work" but I wonder about this.
• Should we go "in depth" on build order? It's important to understand, but also don't want to give the impression that it takes a bunch of thought to get this working (it doesn't)

[guardrex]

I took a look ... yes, indeed! 🎷 ... that looks great. The metadata looks good, and that ToC location is good. I actually think you could go ahead and send a PR to master here now with that.

1. We'll do technical review first with Javier when he gets back.
2. After technical sign-off, I'll make a direct edit pass on the branch here for the grammar+style repo nitpicks.
3. You take a final look to make sure that I didn't break anything 💥🙈 in the process.
4. Merge it and go live.

I know we don't want to endorse third-party tools this much

That's more of a personal thing with me than with MS and the Foundation. I yield to management. Go ahead and place whatever you feel is reasonable/useful. Thus far, that content is very light on specifics. If it stays that light, then perhaps just a link list to 3rd party preprocessor options can appear at the end of your CSS preprocessor support section ... a list where we would welcome 3rd party PRs that add new preprocessors to the list and thus level the playing field for everyone. We wouldn't be picking a (or a couple of) "winners" there.

I'll leave the rest of your bullets to Javier, but I'll mention that I do like the way you handle explaining a bit on how the infrastructure works. We don't do it a lot because in most cases we just want to say 'here's the feature, here's how to use it' and consider the framework's implementation details to be less relevant to most devs. In this case, it works well.

btw-- Javier is OOF at the moment ... stand-by for his response when he gets back.

[daveabrock]

Excellent. Thanks @guardrex.

Yes, I feel some infra is needed. I definitely thought about if it is worth it, but folks are very curious about how to integrate with other tools and to do that, some knowledge is needed.

I'll add a little to the preprocessor section sometime this weekend, then will have a fresh PR waiting for you all on Monday.

Have a good weekend!