Flow: Update App Theme docs to reflect suggested improvements from DX test part-2

[taefi]

Changes needed to be done are as follows:

under Application Theme title:

• Add a Note for minimum Node.js dependency of version ?

Global Styles:

• In the Figure on top of the documentation, a themes folder contents is depicted and there are two files called global.css and document.css. Now, in this section's description document.css is introduced as the file to place the global styles, while it seems that global.css should be here instead, since document.css is targeted for web component exporter theming.

assets:

• Example for referencing assets by appending themes/theme-name to the URI is missing for Java code in the following part:
  

• A brief explanation should be added for each part of an assets block to show what each part means, especially the mapping part. A more detailed (but not too long) description with an example is needed to show what is happening by using that mapping (a brief about those assets being copied to the URI introduced) and the fontawesome/icons must be changed to something like some/local/path and then in the example, it should be fontawesome/icons to support the URL referencing example (currently contains the .../fontawesome/icons/...).

• A Note for adding @NpmPackage to any class in case of using assets from an NPM package with an example or a link to @NpmPackage documentation.
• An example of defining multiple assets block, which is not currently supporting an array similar to importCss.
• The example for using the mapped uri for the background image is referring to a svg icon and can be confusing. Change it to another property other than background-image.

importCss:

• A brief about the concept of importing another CSS file, or a link to another documentation should be added to importCss block.
• There should be at least two examples for using imported css classes both in java (for instance using getStyles().addClassName(“...”) on a Label) and also in html template (<i class="fab ...">).
• A Note for adding @NpmPackage to a desired class, in case of using assets from an NPM package with an example or a link to @NpmPackage documentation.

Creating the theme jar:

• Documentation for creating a Theme.jar should be updated in a way that, first, it shows what should a theme jar look like ( maybe a figure depicting the contents of a jar file, containing the theme folder under src/main/resources/META-INF/resources/themes/ plus an optional Java class for adding @NpmPackage) and then the cookbook instructions of creating a (maven) project and the rest of needed steps.
• Step1 and Step2 of the instructions can be omitted since it is optional to delete test packages or the App.java which may not be created if the developer does not use the archetype and the mvn command.

Using a reusable theme jar:

• Add a last step for adding/updating the @Theme("...") on the App-Shell class by a "theme-name" of existing theme in the jar.
• A Note for consider defining theme.jar packages in a probably existing vaadin.whitelisted-packages = com/example/package, org/brand/anotherpackage for package scanning optimization in application.properties file in SpringBoot applications.

Extending an existing application theme:

• Make the size of this title similar to other headers (e.g. Use application themes or Creating a Reusable Application Theme) and also change the phrase "Extending ..." to something like "Inherite from ...".
• It should be mentioned that the "theme-name" for the child theme must be something different than the parent-theme being inherited. While it is somehow obvious, it worth mentioning there to save some efforts.
• Add a last step, for noting that if an @Theme("...") already exists, it should be updated to the local "theme-name" not the "parent-theme-name".

Other changes:

• Fix typos and formatting issues in the document.
• Descibe the role of theme-name.generated.js iff it is still going to be placed in the theme-name/ folder. If it is going to be converted into a .ts file placed under /target/frontend, this can be ignored.
• Add one upper-level directory in the themes figure to include /frontend too.
• There should be a very short explanation or sign in front of each file in the figure to make the developer distinguish easily the difference between specific-magical files and folders (theme.json, styles.css, components, component-tag-name.css) and other files and folder which can have any names.
• If it's going to be loading only on a special CSS file called styles.css it should be documented. Also, the fact that other CSS files (except component-specific files) should be imported directly into this file in order to be included/applied.
• If having “multiple themes” or “changing themes at runtime” are not available currently, they should be mentioned in the documentation under the limitations header at the very top of the document.

Extracted from the summary part in the DX test document:
https://docs.google.com/document/d/1lwl5BT0lN-VQB5LwK_KvTVzrw8hX_tpNQHj5BW1moRI

[caalador]

Global Styles is not valid after changes for 9741

Assets should note where the assets are copied to e.g. note that they will be added under the themes/theme-name/ + have the target folder there.

importCss the imported css could just be that it always adds body color blue in which instance there would be no extra to add, so also these kinds of cases should be taken into account as not all css need added classnames etc.

Creating the theme jar should perhaps have a view of project files as the contents of a generated jar is not that interesting.

Using a reusable theme jar Spring whitelisting shouldn't probably be delved into in a theming document, but there could be a minor note and a link to the spring documentation or a recommendation to put dependency.java into the package com.vaadin.flow.component, com.vaadin.flow.theme or com.vaadin.shrinkwrap that are always scanned.

On the limitations I don't feel that they should be on the very top of the documentation.

[rolfsmeds]

Re the sample folder structure and the descriptions of the items:

• I would remove the images and webfonts folders from that tree entirely, as they're just examples of how you might structure your theme, not part of the mechanism in any way.
• document.css could be described as "CSS that must be applied to the document root, such as @font-face declarations"
• replace global.css with styles.css, as that will be the automatically loaded stylesheet, and describe it as something along the lines of "Automatically loaded master stylesheet. Other non-component stylesheets need to be imported through styles.css."
• components/ folder description could be "Folder for Vaadin component styles"

[caalador]

Just as a comment on the current state:

document.css and global.css (changed to styles.css) at the moment have the descriptions:

<6> CSS that is always applied to the root of the page (for <<Theming Embedded Web Components,embedded web component>>)
<7> Styles file for the theme that can import other css files, may be applied outside page root

[rolfsmeds]

Right, sorry, I wasn't looking at the latest version. Document.css should probably specify the embedded use case specifically, as above, but also mention that it's really just needed for @font-face etc that must be in the doc root.