Provide ability to detect Calcite version at runtime

[geospatialem]

Check existing issues

• I have checked for existing issues to avoid duplicates

Description

To assist with client issue troubleshooting, the user is seeking to display the Esri JavaScript API version in a simple popup using something similar to the Maps SDK's Kernel.version.

Customers have applications that include a mapping experience with Maps SDK for JS and Calcite Design System and it is known that Calcite updates are independent of the JS updates. The enhancement request, ENH-000165422, would like to include the Calcite Design System version in the information window.

Acceptance Criteria

• Allow users the ability to check the current version of Calcite
• Allow users the ability to add the version to their own custom informational window
• Ensure that context is provided if another product, such as Maps SDK for JS, also uses Calcite has a version
  • Messaging is provided for the Calcite version
  • Messaging is provided for the product (optional)

Relevant Info

ENH-000165422 requested on 02/27/2024

Which Component

N/A - applies to the design system.

Example Use Case

For a user to check the current version of Esri libraries, similar to what is provided in the Maps SDK for JS with Kernel.version for Calcite, where an informational window can provide context to the Calcite version used.

Priority impact

p3 - want for upcoming milestone

Calcite package

• @esri/calcite-components
• @esri/calcite-components-angular
• @esri/calcite-components-react
• @esri/calcite-design-tokens
• @esri/eslint-plugin-calcite-components

Esri team

Calcite (dev)

[driskull]

It would also be helpful to include a version comment in the distribution files.

The Maps SDK includes the following in their files:

// All material copyright Esri, All Rights Reserved, unless otherwise specified.
// See https://js.arcgis.com/4.29/esri/copyright.txt for details.

It would be useful to have a copyright and version like that in ours. Especially in the CSS files since they won't be able to log anything.

[jcfranco]

@driskull We do provide similar info in the source files:

https://unpkg.com/browse/@esri/calcite-components@2.6.0/dist/components/index.js
https://unpkg.com/browse/@esri/calcite-components@2.6.0/dist/calcite/calcite.esm.js

As discussed in our triage session, we might be able to use a similar module or the global config to provide this at runtime.

@geospatialem Is this needed for both the lazy-loaded (dist) and tree-shakeable (components) builds?

[jcfranco]

Explored a few options:

1. component version prop

pros

• allows checking the version at runtime
• each component is versioned
• helps distinguish components defined by different lazy-loading scripts (not too common, but it does happen)
• works for both the lazy-loaded (dist) and tree-shakeable (components) output targets

cons

• adds an extra prop to all components
• increases output size (impact might be mitigated with compression + bundling, and if Stencil ever adds support for a base class or mixin)
  • dist increased ~28kb
  • components increased ~44k (including doc and types)
• need to ensure all components add this property (custom ESLint rule can help here)

2. version export from index.ts (components output target)

pros

• allows consumers to pull in the bundled version and expose wherever needed

cons

• would not be accurate if components are defined by more than one source
• puts burden of exposing the version on developers
• would only work for the components output target

3. adding a version field to a global config object

pros

• simple way to check version for all components
• would only requires updates to the config module

cons

• relies on adding a global
• would not be accurate if components are defined by more than one source as the global would be overridden

[driskull]

would not be accurate if components are defined by more than one source

Is this one a showstopper? Seems like it could be. 🤔

[jcfranco]

For that use case, quite possibly. 😞 Just an idea, but for that particular option, we could add a check for a global version and log a warning message with info on subsequent versions vs overriding.

@dasa Is there an option that would work best from the Maps SDK perspective?

FWIW, @geospatialem has reached out for more info regarding the original request.

[dasa]

Is there an option that would work best from the Maps SDK perspective?

Probably 3 since the version the API is compiled against may not be the version that ends up getting used if the lazy-loaded script is used.

[github-actions]

cc @geospatialem, @brittneytewks

[jcfranco]

[Belated] I think we could proceed w/ option 3 for the next milestone and consider option 1 if Stencil adds support for extending classes (or similar).

[github-actions]

Installed and assigned for verification.

[DitwanP]

🍡 Verified locally on dev

Any app using calcite should have access to the new calciteConfig global.

https://codepen.io/Ditwan-Price/pen/bGyKpbm?editors=1010