docs: confusing setAssetPath recommendation

[maxpatiiuk]

Description

Calcite's get started docs recommend setting this URL for assets:

setAssetPath("https://js.arcgis.com/calcite-components/2.9.0/assets");
// or
defineCustomElements(window, {
  resourcesUrl: "https://js.arcgis.com/calcite-components/2.9.0/assets"
});

This URL is a bit misleading because the assets part at the end of the above URLs is ignored (because it does not end with /)

To reduce confusion, perhaps the documentation should recommend this url instead: https://js.arcgis.com/calcite-components/2.9.0/

NOTE - this is not a breaking change. Explanation:

Under the hood, Calcite calls Stencil's getAssetPath:

export const getAssetPath = (path: string) => {
  const assetUrl = new URL(path, plt.$resourcesUrl$); // plt.$resourcesUrl$ is the result of setAssetPath call()
  return assetUrl.origin !== win.location.origin ? assetUrl.href : assetUrl.pathname;
};

Given this input:

new URL("./assets/icon/i360View24.json", "https://js.arcgis.com/calcite-components/2.9.0/assets");

The end result is:

https://js.arcgis.com/calcite-components/2.9.0/assets/icon/i360View24.json

See that the /assets/ part is present only once in the final URL, despite being present in the string on the left and on the right.
This is because the new URL()'s 2nd argument does not end in /, which leads to the last part (assets) being ignored.
See MDN documentation: https://developer.mozilla.org/en-US/docs/Web/API/URL/URL#:~:text=When%20specify%20a,a%20URL.

So, it works right now, but it's confusing. I would recommend the documentation be changed to clearly show a URL like this: https://js.arcgis.com/calcite-components/2.9.0/

Which Component

all

Resources

No response

[geospatialem]

Summarizing discussions with @jcfranco and @DitwanP on Thurs, Dec 12. Feel free to comment if I missed any additionals 👍🏻:

• Update the framework examples (refer to this link with the content)
• Update the Choose a build section on the doc site
  • Simplify the default, which points to the CDN
  • If not using the CDN, the user will need to specify the assets location
• Update the VS IntelliSense location to the location mentioned in the Lumina PR under Path of extras will change to the following section
• We may need to update the Component on ready section, in the event we don't need to first specify whenDefined Confirmed that this is still needed with @jcfranco

Additional resources:

• Lumina doc on assets
• Lumina doc on getting started
  • It is backwards compatible with Stencil, but public instructions can be simplified a bit compared to Stencil
• Get started changes discussion
• Lumina PR with path of extras
• Maps SDK for JS resources

[github-actions]

Installed and assigned for verification.

[DitwanP]

Verified