feat: document NpmPackage npm assets

[caalador]

Add documentation on copying
npm assets for NpmPackage.

part of vaadin/flow#21806

[github-actions]

AI Language Review

• In the first file, consider aligning the structure with the new one for consistency and avoiding redundant information. This duplication can be seen in the sections about adding npm packages to the project and mapping assets.
• In both files, the explanations are detailed and repetitive, particularly concerning adding npm packages and importing resources. Consider merging overlapping sections and streamlining the information to avoid repetition and enhance clarity. For example, mention the requirement to add packages once per topic or subsection.

[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.

[jouni]

I tried my best by editing this directly on GitHub. I removed mentions to theme.json, and focused only on documenting the @NpmPackage annotation and the assets field, and the @CssImport annotation.