Additional JS initializer scenarios

[guardrex]

Fixes #26363

Since the issue was opened (July, '22), PRs have at least partially addressed the ask. In the first version of JS initializer coverage, our examples merely called console.log. These days, we show how to append custom scripts to the head to load them.

Today, I'm trying to figure out what's missing. What's on this PR might not address all of the asks. What's on here seems to me to be the obvious scenarios.

Here's the original list from the issue ...

• Ensuring that your library is loaded before Blazor Starts.
• Automatically loading the scripts that your library needs.
• Ensuring that Blazor has been initialized before calling into it from your library.

Here are the sections that I thought to add today on top of prior PRs that have improved the coverage ...

• Ensure libraries are loaded in a specific order
• Import additional modules
• Export additional JavaScript in the JavaScript initializers file
• Import map
• Module extension (.js/.mjs)

[MackinnonBuck]

For the scenario:

Ensuring that Blazor has been initialized before calling into it from your library.

I don't think we currently cover this in the JS initializers section of the document. Could we have an example where we interact with one of the Blazor JS APIs in an afterStarted() callback? e.g., register a custom event, add a root component.

[guardrex]

Thanks, @MackinnonBuck ...

• For custom events ... Yes, registration examples are only in a <script> in that coverage. The JS initializers approach isn't shown. I can add an example to that article's coverage, and then cross-link to it both ways.

• For a root component ... Same thing. We only have Blazor.rootComponents.add in an external scripts file. I'll draft an example in that coverage and cross-link both ways.

WRT the updates for this PR, let me get back to you later in the week. I'm working Blazor security topics today, and I'll be on the road moving to another city on Wednesday 🚚. I'll be back on Thursday/Friday to update this PR.

[guardrex]

@MackinnonBuck ... So much for Thursday/Friday! 😄 ... The move across the state of Florida has been a BEAST 👹. Things are stabilizing here now.

WRT the updates thus far, I addressed the feedback points. I'm working the last two items, custom events and root components.

When I started with custom events, I noted that our coverage is lacking. I couldn't get the base case described by the doc to work. I've taken Steve's advice at dotnet/aspnetcore#37012 (comment), and that fixed it. I'm moving on to the JS initializer coverage for it now.

UPDATE: Custom events done ... moving to root components now.

UPDATE: Root components done. Must fix a merge conflict tho. Stand-by ......

[guardrex]

@MackinnonBuck ... Ok ... there's at least enough there for you to punch me 👦🤛😵 on ...

The custom events example for 6.0/7.0 now doesn't use the <script> approach. It goes with a JS initializer, and I cross-linked it from the JS initializer section of the Startup doc.

The root component example keeps it's current showQuote() call to dynamically render the root component. I've added an example to the end where the root component is rendered via a JS initializer, which is also cross-linked from the Startup doc.

While updating the custom event section, I noticed that our current guidance just didn't work OOB following the steps. It really did need Steve's remarks from dotnet/aspnetcore#37012 (comment) rolled into it, so I have that here now. Also ... a NIT ... it needed to have the Microsoft.AspNetCore.Components namespace to light-up the EventHandlerAttribute ... all good now 👍.

I'm more concerned about the root components part, but l'll see what you think.

It might be quicker/easier to look at the review topics. These link to the relevant sections ...

• Event Handling: Custom event arguments section
• Razor components in JS apps: Render Razor components from JavaScript section (it's at the end)
• Startup: JavaScript initializers section

[MackinnonBuck]

Looks good to me! Just a couple remaining questions/suggestions, but I think this should be good to merge after those are addressed 🙂

[guardrex]

Thanks, @MackinnonBuck! 🎸 I'll make those edits and merge this.