npm - jmapcloud-ng-core-types - Versions diffs - 2.0.0 → 2.0.6-qa.3 - Mend

jmapcloud-ng-core-types 2.0.0 → 2.0.6-qa.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/package.json +1 -1
package/public/core.d.ts +6 -15
package/public/jmap/project.d.ts +1 -3
package/public/jmap/startup-options.d.ts +86 -231
package/public/state.d.ts +1 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "jmapcloud-ng-core-types",
-  "version": "2.0.0",
+  "version": "2.0.6-qa.3",
   "description": "JMap Cloud specific version of JMap Cloud NG Core types and interfaces",
   "main": "index.js",
   "types": "ambient.d.ts",

package/public/core.d.ts CHANGED Viewed

@@ -139,7 +139,7 @@ export {}
  *
  * After being loaded, the **NG Core** library is accessible through the namespace **JMap** in the javascript console. For example :
  * ```ts
- * // returns the JMap Cloud NG Core version.
+ * // returns the JMap Cloud NG package version.
  * JMap.getVersion()
  * ```
  */
@@ -147,11 +147,11 @@ export namespace JMap {
   /**
    * **JMap.getVersion**
    *
-   * Returns the JMap Cloud NG Core library build version.
+   * Returns the JMap Cloud NG npm package version.
    *
    * @example
    * ```ts
-   * // returns the build version, for example "1.0.1"
+   * // returns the package version, for example "2.0.5-qa.10"
    * JMap.getVersion()
    * ```
    */
@@ -159,13 +159,11 @@ export namespace JMap {
   /**
    * **JMap.getApiVersion**
    *
-   * Returns the JMap Cloud NG Core library API (typescript interfaces) version.
-   *
-   * For the same API version, multiple implementation versions can exist.
+   * Returns the JMap Cloud NG npm package version.
    *
    * @example
    * ```ts
-   * // returns the API version, for example "1.0.1"
+   * // returns the package version, for example "2.0.5-qa.10"
    * JMap.getApiVersion()
    * ```
    */
@@ -5806,14 +5804,7 @@ export namespace JMap {
     /**
      * **JMap.Project.getMapUnit**
      *
-     * Returns the project map unit.
-     *
-     * @throws if no project is loaded
-     * @example
-     * ```ts
-     * // return "meters", or "kilometers", or "miles", or "yards"...
-     * JMap.Project.getMapUnit()
-     * ```
+     * @deprecated Use {@link getDefaultDistanceUnit} instead. mapUnit has been removed from projects. Always returns "meters".
      */
     function getMapUnit(): JMAP_DISTANCE_UNITS
     /**

package/public/jmap/project.d.ts CHANGED Viewed

@@ -31,11 +31,9 @@ export interface JProjectServerExtension {
   version: string
 }
-export interface JProject extends Omit<McsComponents["schemas"]["LocalizedProjectDTO"], "mapUnit" | "distanceUnit" | "displayUnit" | "initialExtent" | "maximumExtent" | "terrain"> {
+export interface JProject extends Omit<McsComponents["schemas"]["LocalizedProjectDTO"], "distanceUnit" | "initialExtent" | "maximumExtent" | "terrain"> {
   defaultLanguage: LOCALES
-  mapUnit: JMAP_DISTANCE_UNITS
   distanceUnit: JMAP_DISTANCE_UNITS
-  displayUnit: JMAP_DISTANCE_UNITS
   initialExtent: JBounds | null
   maximumExtent: JBounds | null
   terrain?: JTerrainSpecification

package/public/jmap/startup-options.d.ts CHANGED Viewed

@@ -16,100 +16,42 @@ export type JWindow = globalThis.Window & {
 }
 /**
- * This section is about the JMAP Library startup options.
+ * Startup options for JMap Cloud NG.
  *
- * JMap library executable is available through a CDN url.
+ * Set `window.JMAP_OPTIONS` before loading the JMap Cloud NG script. The same
+ * package can start with the full interface (`ui: "full"`, the default) or with
+ * a minimal interface (`ui: "minimal"`).
  *
- * The URL is like "https://cdn.jsdelivr.net/npm/jmap-core-js@0.5.0/public/",
- * but it depends on the version you want to use.
- *
- * First you need to import our JS file in your http file, in order to load the JMap Cloud NG Core library.
- * It's recommended to put the CDN import at the end of the body tag, like that :
  * ```html
- * ...
  * <html>
- *   ...
  *   <body>
- *     ...
- *     <!-- !!! Insert the import at the end of the body tag !!! -->
- *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/"></script>
- *   </body>
- * </html>
- * ```
- * To make the JMap Cloud NG Core library working you need to provide some required information like :
- *
- *   - Your JMap Server Rest API URL
- *   - The project id to open
- *   - A valid JMap user session token, **or** set the JMap Cloud NG Core library to log as "anonymous"
- *
- * It can be passed by setting a global JS variable named "JMAP_OPTIONS" :
- *
- * ```html
- * <html>
- *   <body>
- *     <script type="text/javascript">
- *       window.JMAP_OPTIONS = {
- *         // a valid project id
- *         projectId: 10,
- *         // a valid JMap server Rest url
- *         restBaseUrl: "http://my-jmap-server/services/rest/v2.0",
- *         session: {
- *           // a valid session token
- *           token: 2345677654
- *         }
- *         ... // other optional JMAP params
- *       }
- *     </script>
- *     ... your web page
- *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/"></script>
- *   </body>
- * </html>
- * ```
- *
- * Below a full example of how to start the JMap library in a web page,
- * where parameters ***ngToken*** and ***ngProjectId*** are get from the url :
- * ```html
- * <!DOCTYPE html>
- * <html>
- *   <head>
- *     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
- *     <meta charset="UTF-8">
- *   </head>
- *   <body class="jmap_wrapper">
- *    <script type="text/javascript">
- *       const url = new URL(window.location.href)
- *       const token = url.searchParams.get("ngToken")
- *       let projectId = Number(url.searchParams.get("ngProjectId"))
- *       if (isNaN(projectId)) {
- *         projectId = 0
- *       }
+ *     <script>
  *       window.JMAP_OPTIONS = {
- *         projectId: Number(projectId),
- *         restBaseUrl: "http://your-jmap-server-url/services/rest/v2.0",
- *         token: token
+ *         restBaseUrl: "https://api.example.com",
+ *         ui: "minimal",
+ *         projectId: "my-project-id",
+ *         organizationId: "my-organization-id",
+ *         anonymous: true
  *       }
  *     </script>
- *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/index.js">
- *     </script>
+ *     <script defer src="https://cdn.jsdelivr.net/npm/jmapcloud-ng@x.x.x/public/index.js"></script>
  *   </body>
  * </html>
  * ```
  *
- * For example, you can pass this parameters like that :
- *   - **http:// my-company/my-custom-page-using-jmap?ngToken=95423672742&ngProjectId=10**.
- *
- * When JMap Cloud NG Core library starts, if the **JMap token "*95423672742*"** is valid, it will automatically load
- * the **JMap project id=*10***, then load the map in the **div id="*jmap-map*"**.
+ * `restBaseUrl` is required. It must point to the JMap Cloud API used by this
+ * NG instance. Project and authentication options depend on the integration:
+ * a page can open a known project directly, start anonymously for a public
+ * project, or rely on the normal interactive authentication flow.
  */
 export interface JCoreOptions {
   /**
-   * The JMap project id.
+   * The JMap Cloud project id to open at startup.
    *
-   * If both a project id and a project name are provided, project id will be used.
+   * If both a project id and a project name are provided, the project id is used.
    *
-   * If no project name or id are set, the library will do noting, you will have a blank page.
-   *
-   * So if you want the library to load the project automatically, you need to set the project id.
+   * If no project name or id is set, NG starts without automatically opening a
+   * project. The full UI can still let the user choose a project when available.
    *
    * ```html
    * <html>
@@ -129,15 +71,15 @@ export interface JCoreOptions {
    */
   projectId?: JId
   /**
-   * A JMap project name.
-   *
-   * If you can prefer using the project id over the name.
+   * The JMap Cloud project name to open at startup.
    *
-   * If both a project id and a project name are provided, project id will be used.
+   * Prefer using `projectId` when possible because names are not guaranteed to
+   * be stable.
    *
-   * If no project name or id are set, the library will do noting, you will have a blank page.
+   * If both a project id and a project name are provided, the project id is used.
    *
-   * So if you want the library to load the project automatically, you need to set the project name (or id).
+   * If no project name or id is set, NG starts without automatically opening a
+   * project. The full UI can still let the user choose a project when available.
    *
    * ```html
    * <html>
@@ -157,9 +99,9 @@ export interface JCoreOptions {
    */
   projectName?: string
   /**
-   * If provided this function will be processed when the list of projects is received from the server :
+   * Called when the project list is received from the JMap Cloud API.
    *
-   * the event receives a JProjectAllEventParams object
+   * The event receives a `JProjectAllEventParams` object.
    *
    * ```html
    * <html>
@@ -181,11 +123,12 @@ export interface JCoreOptions {
    */
   onProjectsChange?(params: JProjectAllEventParams): void
   /**
-   * By default project thumbnails are not loaded, because they are not useful if JMap Cloud NG Core lib is used alone.
+   * By default, project thumbnails are not loaded because they are only needed
+   * when the integration displays project choices.
    *
-   * To load asynchronously project thumbnails, set startup option "loadProjectThumbnails" to true.
+   * To load project thumbnails asynchronously, set `loadProjectThumbnails` to true.
    *
-   * JMap Cloud NG Core lib will load all project thumbnails (or preview) in project objects (property "base64ImageThumbnail").
+   * NG will load project thumbnails into the `base64ImageThumbnail` property.
    *
    * The thumbnail is stored as a base64 string image, that you can use to set an img src attribute directly.
    *
@@ -214,11 +157,12 @@ export interface JCoreOptions {
    */
   loadProjectThumbnails?: boolean
   /**
-   * The JMap Server Rest API url.
+   * The JMap Cloud API base URL.
    *
-   * Default value is : http://localhost:8080/services/rest/v2.0 (for test only).
+   * This option is required. There is no default value because a JMap Cloud NG
+   * instance can be embedded from a page hosted on a different domain than the
+   * API it must call.
    *
-   * If your are not testing you must provide the url of your JMap REST API :
    * ```html
    * <html>
    *   ...
@@ -226,8 +170,7 @@ export interface JCoreOptions {
    *     <script type="text/javascript">
    *       window.JMAP_OPTIONS = {
    *         ...
-   *         // a valid JMap REST Api url
-   *         restBaseUrl: "http://my-custom-jmap-server-url/services/rest/v2.0"
+   *         restBaseUrl: "https://api.example.com"
    *       }
    *     </script>
    *     ...
@@ -237,13 +180,9 @@ export interface JCoreOptions {
    */
   restBaseUrl?: string
   /**
-   *
-   * "***anonymous***" must be specified together with a valid {@link JCoreOptions.organizationId}, otherwise it will not be taken into account
-   *
-   * If the project you access can be accessed anonymously,
-   * you are not forced to pass a session token but you have
-   * to explicitly tell the JMap Cloud NG library to log as an anonymous
-   * user by setting the "***anonymous***" parameter like that :
+   * If the selected project is public, NG can start an anonymous session.
+   * `anonymous` must be specified together with a valid
+   * {@link JCoreOptions.organizationId}, otherwise it is ignored.
    *
    * ```html
    * <html>
@@ -251,34 +190,33 @@ export interface JCoreOptions {
    *   <body>
    *     <script type="text/javascript">
    *       window.JMAP_OPTIONS = {
-   *         // a valid project id
-   *         projectId: 10,
-   *         // a valid JMap Server Rest url
-   *         restBaseUrl: "http://my-jmap-server/services/rest/v2.0",
-   *         // The anonymous parameter
+   *         restBaseUrl: "https://api.example.com",
+   *         projectId: "my-project-id",
+   *         organizationId: "my-organization-id",
    *         anonymous: true
-   *         // The organization id
-   *         organizationId: "some-valid-id"
-   *         ... // other optional JMAP params
    *       }
    *     </script>
    *
    *     ... your web page
    *
-   *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/"></script>
+   *     <script defer src="https://cdn.jsdelivr.net/npm/jmapcloud-ng@x.x.x/public/index.js"></script>
    *   </body>
    * </html>
    * ```
    */
   anonymous?: boolean
   /**
-   * The default authentication method in NG is now using an oAuth2 setup. This allows sharing session with JMap Cloud's Portal.
+   * Enables the legacy refresh-token authentication flow.
    *
-   * However, if for technical reasons you need to revert to a REST API-based technique of authentication, you can do it by setting ***legacyAuthentication*** to "true".
+   * By default, JMap Cloud NG uses the configured OAuth2 authentication flow so
+   * it can share a browser session with the JMap Cloud portal.
    *
-   * {@link JCoreOptions.anonymous} has precedence over ***legacyAuthentication***.
+   * Use `legacyAuthentication: true` only for integrations that still need the
+   * refresh-token based flow. {@link JCoreOptions.anonymous} has precedence over
+   * `legacyAuthentication`.
    *
-   * If you specify a {@link JCoreOptions.token}, ***legacyAuthentication*** will automatically be activated. This may change in the future.
+   * Specifying {@link JCoreOptions.token} automatically enables legacy
+   * authentication. This may change in the future.
    *
    * ```html
    * <html>
@@ -286,137 +224,74 @@ export interface JCoreOptions {
    *   <body>
    *     <script type="text/javascript">
    *       window.JMAP_OPTIONS = {
-   *         // a valid project id
+   *         restBaseUrl: "https://api.example.com",
    *         projectId: "<project-uuid>",
-   *         // a valid JMap Cloud Rest url
-   *         restBaseUrl: "http://my-jmap-server/",
-   *         // The legacyAuthentication parameter
    *         legacyAuthentication: true
-   *         ... // other optional JMAP params
    *       }
    *     </script>
    *
    *     ... your web page
    *
-   *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/"></script>
+   *     <script defer src="https://cdn.jsdelivr.net/npm/jmapcloud-ng@x.x.x/public/index.js"></script>
    *   </body>
    * </html>
    * ```
    */
   legacyAuthentication?: boolean
   /**
-   * A JMap user's session refresh token.
+   * A JMap Cloud refresh token for the legacy authentication flow.
    *
-   * If you want to open a session automatically without user interaction and you don't use the library anonymously
-   * (see the ***{@link JCoreOptions.anonymous}*** parameter in this section), you must provide a JMap Cloud refresh
-   * token to the JMap library to initialize the user session.
+   * Prefer the default OAuth2 authentication flow for new integrations. Use this
+   * option only when your integration already obtains a refresh token and needs
+   * to open a session without user interaction.
    *
    * A refresh token can be used only once.
    *
-   * Specifying ***token*** will automatically activate {@link JCoreOptions.legacyAuthentication}
-   *
-   * To get a refresh token, you can use the JMap Rest API on your JMap Cloud Server.
-   * See [JMap.User.setToken](../functions/JMap_Cloud_NG_Core___API.JMap.User.setToken.html) for detailed examples on how to fetch a token through JMap's REST API.
+   * Specifying `token` automatically activates {@link JCoreOptions.legacyAuthentication}.
    *
-   * So to start the library using the fetched token you can configure your startup options like this :
    * ```html
    * <html>
    *   ...
    *   <body>
    *     <script type="text/javascript">
    *       window.JMAP_OPTIONS = {
-   *         token: "some-valid-refresh-token"
+   *         restBaseUrl: "https://api.example.com",
+   *         token: "some-valid-refresh-token",
+   *         organizationId: "my-organization-id"
    *       }
    *     </script>
    *     ...
-   *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/"></script>
+   *     <script defer src="https://cdn.jsdelivr.net/npm/jmapcloud-ng@x.x.x/public/index.js"></script>
    *   </body>
    * </html>
    * ```
-   *
-   * If you don't want to make an AJAX call to the REST API, you can use the JMap library to login (JMap will make the AJAX call to the rest API). You have to wait for the lib to be loaded and the server to be ready to accept requests.
-   *
-   * To know if the lib has been loaded you can check if the JMAp namespace exists or not. See below for an example:
-   *
-   * ```html
-   * <!DOCTYPE html>
-   *   <html>
-   *     ...
-   *     <body class="jmap_wrapper">
-   *       <script type="text/javascript">
-   *         console.log("JMap", window.JMap)
-   *         window.JMAP_OPTIONS = {
-   *           projectId: 35,
-   *           restBaseUrl: "https://jmap7dev.jmaponline.net/services/rest/v2.0",
-   *           map: {
-   *             zoom: 9.757829447748511,
-   *             center: {
-   *               x: -73.66415865898597,
-   *               y: 45.53583011032552
-   *             }
-   *           }
-   *         }
-   *       </script>
-   *       ...
-   *       <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/index.js"></script>
-   *       <script>
-   *         (function jmapLogin() {
-   *           if (window.hasOwnProperty("JMap") && JMap.Server.isReady()) {
-   *             JMap.User.login("jdo@company.com", "xxx")
-   *           } else {
-   *             console.log("Waiting for the JMap lib to be loaded ...")
-   *             setTimeout(() => jmapLogin(), 150) // check every 150 milliseconds
-   *           }
-   *         })()
-   *       </script>
-   *     </body>
-   *   </html>
-   * ```
-   *
    */
   token?: string
   /**
-   * The JMap Cloud organization id associated with the refresh token.
-   *
-   * For JMap CLoud only. Only taken into account if a refresh token has been passed via the {@link JCoreOptions.token} startup option (or the equivalent hash parameter version)
-   * ***or*** if the "anonymous" option has been passed, together with a project id.
+   * The JMap Cloud organization id associated with the session.
    *
-   * You can pass this organization id to open a session on JMap Cloud via the startup options.
-   *
-   * A typical usage for a session opening:
-   * ```html
-   * <html>
-   *   ...
-   *   <body>
-   *     <script type="text/javascript">
-   *       window.JMAP_OPTIONS = {
-   *         token: "v1.MRq [.....] Rehef72YWws", // a refresh token
-   *         organizationId: "my-organization-id"
-   *       }
-   *     </script>
-   *     ...
-   *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/"></script>
-   *   </body>
-   * </html>
-   * ```
+   * This option is required when using {@link JCoreOptions.token}. It is also
+   * required when using {@link JCoreOptions.anonymous} with a public project.
    *
-   * A typical usage for a JMap Cloud public project:
+   * A typical usage for a public project:
    * ```html
    * <html>
    *   ...
    *   <body>
    *     <script type="text/javascript">
    *       window.JMAP_OPTIONS = {
+   *         restBaseUrl: "https://api.example.com",
    *         anonymous: true,
    *         projectId: "my-project-id",
    *         organizationId: "my-organization-id"
    *       }
    *     </script>
    *     ...
-   *     <script defer type="text/javascript" src="https://cdn.jsdelivr.net/npm/jmap-core-js@x.x.x/public/"></script>
+   *     <script defer src="https://cdn.jsdelivr.net/npm/jmapcloud-ng@x.x.x/public/index.js"></script>
    *   </body>
    * </html>
-   * ```   */
+   * ```
+   */
   organizationId?: string
   /**
    * By default the geolocation service is enabled.
@@ -448,7 +323,7 @@ export interface JCoreOptions {
   /**
    * Optional extensions.
    *
-   * Click {@link JCoreExtension} to get details about how defining an extension.
+   * See {@link JCoreExtension} for extension configuration details.
    */
   extensions?: JCoreExtension[]
   /**
@@ -462,37 +337,30 @@ export interface JCoreOptions {
    */
   locale?: string
   /**
-   * Call when the JMap library is loaded
+   * Called when JMap Cloud NG is loaded.
    */
   onReady?: () => void
   /**
-   * As a developer, you can override a project's extension jsUrl during development.
-   *
-   * Ex: the extension having id="custom-extension" is set on the project. Its unique identifier is:
-   * * for JMap Server: `serverExtensionId` = "my.extention.classPath"
-   * * for JMap Cloud: `jmapCloudExtensionUrn` = "949079ff-d021-45dd-93c0-611bfcebfc2b"
+   * Overrides a project's extension `jsUrl` during development.
    *
-   * Its jsUrl is "https://cdn.jsdelivr.net/npm/custom-extension@1.0.10/public/index.js"
+   * Use this when a project references a published extension but you want NG to
+   * load your local development build instead.
    *
-   * During development, you need to be able to load your local code instead of the code located at the extension's jsUrl location.
+   * Example: the project references an extension whose JMap Cloud extension URN is
+   * `"949079ff-d021-45dd-93c0-611bfcebfc2b"`, and whose published `jsUrl` is
+   * `"https://cdn.jsdelivr.net/npm/custom-extension@1.0.10/public/index.js"`.
    *
-   * Your local development code could for instance be available at: "https://localhost:8083/build/index.js".
+   * Your local development build could be available at
+   * `"https://localhost:8083/build/index.js"`.
    *
-   * In order to change the extension jsUrl dynamically, you can set your `JMAP_OPTIONS.extensionsUrlOverride` property like this:
-   *
-   * For JMAp Server:
-   * [{
-   *  extensionUniqueIdentifier: "my.extention.classPath",
-   *  jsUrl: "https://localhost:8083/build/index.js"
-   * }]
+   * You can then set `JMAP_OPTIONS.extensionsUrlOverride` like this:
    *
-   * For JMap Cloud:
+   * ```javascript
    * [{
    *  extensionUniqueIdentifier: "949079ff-d021-45dd-93c0-611bfcebfc2b",
    *  jsUrl: "https://localhost:8083/build/index.js"
    * }]
-   *
-   *
+   * ```
    */
   extensionsUrlOverride?: JExtensionServerOverride[]
   /**
@@ -500,31 +368,18 @@ export interface JCoreOptions {
    * startup option (`"full"` | `"minimal"`) or the `?ngUi=` URL parameter instead. Kept
    * for source compatibility and will be removed in a future major version.
    *
-   * Previously: setting this to `true` suppressed NG Core's built-in main layout
+   * Previously: setting this to `true` suppressed the built-in boot shell
    * (loader, login panel, project selection panel).
    */
   hideMainLayout?: boolean
   /**
-   * Selects which UI shell ng renders on top of the always-loaded core map.
+   * Selects which UI shell NG renders on top of the map runtime.
    *
    *  - `"full"` (default) loads the full NG side-panel UI as a lazy chunk.
-   *  - `"minimal"` boots only the core map and skips the full-UI chunk entirely.
+   *  - `"minimal"` boots the map runtime and skips the full-UI chunk entirely.
    *
    * Equivalent to the `?ngUi=full|minimal` URL parameter (also accepted as `#ngUi=…`); this
    * option wins when both are set.
    */
   ui?: "full" | "minimal"
-  /**
-   * Test-only: pin the AppShell to a specific boot stage so containment / visual specs
-   * can drive every pre-app surface deterministically without sequencing a real boot.
-   *
-   * Accepted values: `"connecting" | "login" | "orgs" | "projects" | "openingProject" |
-   * "chunkError" | "error.serverInfo" | "error.anonymousLogin"`.
-   *
-   * Also accepts a `?__bootStage=<stage>` URL query parameter (useful for iframe
-   * scenarios where `JMAP_OPTIONS` is set inside the framed document). This is
-   * wired up exclusively for the rendering-tests harness; do not set it in any
-   * production boot.
-   */
-  testBootStageOverride?: string
 }

package/public/state.d.ts CHANGED Viewed

@@ -193,4 +193,5 @@ export interface JServerState extends JServerInfo {
   isReady: boolean
   isLoading: boolean
   hasLoadingError: boolean
+  missingRestBaseUrl: boolean
 }