feat: document NpmPackage npm assets

[caalador]

Add documentation on copying
npm assets for NpmPackage.

part of vaadin/flow#21806

[github-actions]

AI Language Review

The revised document has been updated to include new sections regarding the use of the NpmPackage annotation. These sections outline how to load resources directly without requiring a custom theme or theme.json file. Annotations such as @NpmPackage and @CssImport are introduced with examples.

One point to address is an oversight on the filename for the example under "Loading Stylesheets from npm Packages Using the CssImport annotation." The comment preceding the code block states "Sample asset mapping with NpmPackage annotation," whereas it should refer to the CssImport annotation instead. Adjust the comment to accurately reflect the annotation demonstrated in the code block.

[knoobie]

No mention of CSS? I'm wondering because this would also replace the theme.json's importCss, or?

[caalador]

Haven't thought about that, but you could of copy any css as an asset and then have a @CssImport for it to load the css.

[caalador]

I'll test around a bit and add the information to the document.

[knoobie]

Might be out of scope.. but I wanted to mention it because the ticket from above says "In Vaadin 25 we are going to deprecated Theme annotation and features in theme.json, including importCss instruction that then needs a replacement." and I was wondering where my importCss replacement is :)

[caalador]

As a quick test it would seem that we don't need anything new as the following seems to work

@NpmPackage(value = "@fortawesome/fontawesome-free", version = "5.15.1")
@CssImport("@fortawesome/fontawesome-free/css/all.css")
@Route("theme")
public class ThemeView extends Div {
    public ThemeView() {
        Span sharp = new Span();
        sharp.addClassNames("fa-sharp","fa-solid","fa-user");
        sharp.getStyle().set("font-family", "'Font Awesome 5 Free'");
        add(sharp);
    }
}

But this might need some extra testing to see that it wasn't just a fluke or something in the test module enabling this..

[knoobie]

Thanks for checking! Previously people could do it also like this:

{
  "parent": "my-base-theme",
  "importCss": ["@fortawesome/fontawesome-free/css/all.min.css"],
  "lumoImports": ["typography","color","spacing","badge","utility"]
}

[jouni]

Is ThemeResource still a thing, even after the deprecation of the ´@Theme` annotation? Also, talking about a “custom theme” might be problematic, referring to the old theme mechanics, rather than just regular stylesheets.

Suggested change

	This difference is due to the custom theme call having the `themes/[themeName]/` in the request letting us know it is a theme resource, making it possible to prepend the static part.
	This difference is due to the custom theme call having the `themes/[themeName]/` in the request letting Vaadin know it's a theme resource, making it possible to prepend the static part.

[tltv]

Theme annotation will be deprecated along the themes/[themeName] path but it's still supported. After deprecation, "theme resource folder" is relevant only for apps still using it. For those it's "custom theme" and for new apps it's just regular css.

This article could have a reference to https://vaadin.com/docs/latest/styling/advanced/npm-packages#styles-from-npm to make it clearer what "custom theme" mean.

[jouni]

Ah, I see the text before talking about the difference. But since this is the documentation for Vaadin 25, I don't think we should mention deprecated APIs at all, but guide users to use just the supported APIs.

I would remove any mentions and comparisons to theme.json, custom themes and theme resources. @peholmst, would you agree?

[peholmst]

Yes! Don't mention anything deprecated. Only mention what's current and recommended.