@c8y/options 1020.0.4

package/README.md

@@ -0,0 +1,25 @@
+**`@c8y/options` Package Overview**
+
+The `@c8y/options` package plays a crucial role in configuring and customizing Cumulocity applications. At the heart of this package lies the `ApplicationOptions` interface, which serves as a comprehensive blueprint for defining various aspects of your application. Here's what it offers:
+
+1. **Application Metadata**: Allows you to specify essential details about your application, such as its name, context path, key, version, description, author, and license.
+
+2. **Hybrid App Support**: Enables you to indicate whether your application is a hybrid one, utilizing both Angular and AngularJS simultaneously.
+
+3. **Branding and Styling**: Provides options to customize the look and feel of your application, including paths to branding entry files, custom CSS variables, and favicon URLs.
+
+4. **Localization**: Supports the addition and override of languages available in the application, as well as the inclusion of custom translations.
+
+5. **Documentation and Support**: Allows you to configure documentation links, support URLs, and guide templates to assist your application's users.
+
+6. **UI Customization**: Offers a wide range of options to tailor the user interface, such as hiding the app switcher, header, or powered-by information, enabling breadcrumbs, and adjusting the layout of tabs and navigators.
+
+7. **Feature Toggles**: Provides flags to enable or disable specific features like storage limitation, cloud sensor wizard, newsletter subscription, and more.
+
+8. **Integration Options**: Allows integration with third-party services and tools, such as specifying a Gainsight key for product experience tracking.
+
+9. **Plugin and Package Support**: Facilitates the development of packages and the integration of plugins, including the definition of version matrices for managing dependencies.
+
+10. **Map Configuration**: Enables customization of map layers, default zoom levels, and center positions, as well as the configuration of geocoding services.
+
+The `@c8y/options` package, with its `ApplicationOptions` interface, offers a flexible and extensive set of configuration options to tailor your Cumulocity application to your specific needs, making it a powerful tool in your development arsenal.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@c8y/options",
+  "version": "1020.0.4",
+  "license": "Apache-2.0",
+  "author": "Cumulocity",
+  "description": "Cumulocity application options",
+  "types": "./src/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "echo 'No build needed'"
+  },
+  "keywords": [
+    "Cumulocity",
+    "IoT",
+    "m2m",
+    "application",
+    "options"
+  ],
+  "peerDependencies": {
+    "@c8y/client": "1020.0.4"
+  }
+}

package/src/ApplicationOptions.d.ts

@@ -0,0 +1,421 @@
+import { IApplication, VersioningMatrix } from '@c8y/client';
+
+/*
+ * -----------------------------WARNING---------------------------------
+ * This file has is an interface for packages/ngx-components/core/common/ApplicationOptions.
+ * Any changes to this file must be reflected there, too.
+ */
+export interface ApplicationOptions {
+  /** Application name (saved to the server). */
+  name: string;
+  /** Application context path (saved to the server). */
+  contextPath: string;
+  /** Application key (saved to the server). */
+  key: string;
+  /** The version of the application */
+  version: string;
+  /** The version of the used WebSDK version */
+  webSdkVersion?: string;
+  /** The description of the application */
+  description?: string;
+  /** The author of the application */
+  author?: string;
+  /** The license of the application */
+  license?: string;
+  /**
+   * Set to `true` if the application is hybrid and uses Angular and AngularJS simultaneously.
+   */
+  upgrade?: boolean;
+  /**
+   * Path to the branding entry file. (Set it to false to disable any styling. You can handle the styling then on your own e.g. in an angular.json file using ng-cli)
+   */
+  brandingEntry?: string | boolean;
+  /**
+   * URL to dynamically fetched options.
+   * If set to `true` or left undefined, an URL will be used based on the applications contextPath.
+   * If set to `false`, no dynamic options will be fetched.
+   * */
+  dynamicOptionsUrl?: string | boolean;
+  /** URL to favicon. */
+  faviconUrl?: string;
+  /** URL to *.css file which will replace default branding. */
+  brandingUrl?: string;
+  /** Object with properties that will be converted to CSS custom variables. */
+  brandingCssVars?: BrandingCssVars;
+  /**
+   * Allows for adding or overriding languages available in the application.
+   *
+   * Its keys are language codes and its values are objects with the following properties:
+   *
+   * - `name`: English name of the language,
+   * - `nativeName`: native name of the language,
+   * - `url`: full URL to JSON file with compiled translations;
+   *    if not defined, translations will be loaded from `${localePath}/${langCode}.json`.
+   *
+   * Example:
+   * ```json
+   * "languages": {
+   *   "de": {
+   *     "name": "German",
+   *     "nativeName": "Deutsch",
+   *     "url": "/apps/public/ui-assets/de.json"
+   *   }
+   * }
+   * ```
+   */
+  languages?: Languages;
+  /**
+   * Allows for adding custom translations. It is an optional property.
+   *
+   * Its keys are language codes (https://cumulocity.com/docs/section/getting_started/#a-name-languages-a-available-languages)
+   * and its values are objects with key-value pairs, where the key is the original string in English and the value - its translation.
+   *
+   * - `Home`: "Startseite"
+   *
+   * For example, you can add the translation of your custom cookie banner configured in the branding settings:
+   * ```json
+   * "i18nExtra": {
+   *   "de": {
+   *     "About cookies on Cumulocity IoT": "Informationen zu Cookies in Cumulocity IoT",
+   *     "Click Agree and Proceed to accept cookies and go directly to the platform or click on Privacy Policy to see detailed descriptions of the used cookies.": "Klicken Sie auf Zustimmen und fortfahren, um Cookies zu akzeptieren und direkt zur Plattform zu gelangen, oder klicken Sie auf Datenschutzrichtlinie, um detaillierte Beschreibungen der verwendeten Cookies anzuzeigen."
+   *   }
+   * }
+   * ```
+   */
+  i18nExtra?: I18nExtra;
+  /** Array of URLs to additional *.css files to be loaded at runtime. */
+  extraCssUrls?: string[];
+  /** Documentation links settings. */
+  docs?: Docs;
+  /** Application icon to be displayed in app switcher and header bar. */
+  icon?: Icon;
+
+  // These are the old options
+  /** Hide application in app switcher (saved to the server). */
+  noAppSwitcher?: boolean;
+  /** HTML page title. */
+  globalTitle?: string;
+  /** Hide "powered by" and version info at the bottom of the navigator and in the right drawer. */
+  hidePowered?: boolean;
+  /** Hides the header bar */
+  hideHeader?: boolean;
+  /** Hides the "Platform information" in the right drawer, will overrule the "hidePowered" option */
+  hidePlatformInformation?: boolean;
+  /** Shows the link to support page. Accepts values:
+   * false, hide the link
+   * string, value of url to be shown
+   */
+  supportUrl?: boolean | string;
+  /**
+   * Replacement string for `user` field in audit logs for actions performed by a support user
+   * (available placeholders: `{{support_user}}`, `{{supported_user}}`).
+   */
+  supportUserString?: string;
+  /**
+   * Disables realtime updates on the map widget and maps in general.
+   */
+  mapWidgetRealtimeDisabled?: boolean;
+  /**
+   * Allows to adjust the default pagesize of 100 items of the map widget and maps in general.
+   */
+  mapWidgetPageSize?: number;
+  /**
+   * Allows to hide the hint that there are more devices with geo coordinates then displayed on the map widget and maps in general.
+   */
+  mapWidgetHideMaxDeviceOnMapHint?: boolean;
+  /** Enable or disable the right drawer. */
+  rightDrawer?: boolean;
+  /** Enable or disable breadcrumbs in the header for groups and devices (default: false). */
+  breadcrumbs?: boolean;
+  /** Collapse navigator on initial load. */
+  hideNavigator?: boolean;
+  /** Show tabs horizontally or vertically. */
+  tabsHorizontal?: boolean;
+  /** Additional link to display on login screen. */
+  loginExtraLink?: LoginExtraLink | LoginExtraLink[];
+  /** Enable or disable storage limitation feature. */
+  storageLimitationFeatureEnabled?: boolean;
+  /** Name of company handling support requests from app users (displayed in notification message). */
+  companyName?: string;
+  /** URL template for documentation links (default: `'${docsBaseUrl}${partialUrl}'`). */
+  guideHrefTemplate?: string;
+  /** Base URL for documentation links (include `{{ version }}` placeholder, if you want versioned links). */
+  docsBaseUrl?: string;
+  /** CSP string to be applied to `index.html` by replacing default values. */
+  contentSecurityPolicy?: string;
+  /** Enables cloud sensor wizard */
+  sensorPhone?: boolean;
+  /** Show or hide a newsletter subscription checkbox in edit user modal. */
+  newsletter?: boolean;
+  /** Cookie Banner configuration */
+  cookieBanner?: CookieBannerConfiguration;
+  /** Cookie preferences configuration. Here you can enable or disable cookie categories */
+  cookiePreferences?: CookiePreferencesConfiguration;
+  /** A key for the product experience software Gainsight. */
+  gainsightKey?: string;
+  /** Disable user tracking */
+  disableTracking?: boolean;
+  /** NgModule export for plugins. */
+  exports?: PluginsExports[];
+  /** List of imported remote plugins. */
+  remotes?: RemotePlugins;
+  /** If set to true, only remotes defined in the `remotes` query parameter will be loaded. */
+  forceUrlRemotes?: boolean;
+  /**
+   * Defines if the application is a package. Packages can be distributed as blueprint or allow plugins.
+   */
+  isPackage?: boolean;
+  /**
+   * Defines what is contained in the package.
+   */
+  package?: 'plugin' | 'blueprint';
+  /** The package source a application origins from as IApplication or simply the id of the source */
+  source?: string | number | IApplication;
+  /**
+   * Allows to enable or disable context help, or to override the default base URL used to load its contents.
+   * By default, the context help uses the same base URL as defined in the `docsBaseUrl` option
+   * (if this option is undefined, then the following value will be used: `https://www.cumulocity.com`).
+   * Alternatively, if a string is provided here, it'll be used as the base URL
+   * and any `{{ version }}` placeholder will be replaced with the relevant docs version.
+   */
+  contextHelp?: boolean | string;
+  /**
+   * By default, cockpit and devicemanagement use the onlyRoots query to resolve root nodes. This
+   * could lead to performance issues, if a customer has a lot of root nodes. Therefore you can disable
+   * the use of this query with this flag.
+   */
+  disableOnlyRootsQuery?: boolean;
+  /**
+   * Allows to force showing the setup wizard.
+   */
+  forceSetup?: boolean;
+  /**
+   * Indicates if the application needs to show the setup wizard.
+   */
+  isSetup?: boolean;
+  /**
+   * By default a WebSDK app requires the user to be logged in.
+   * In case you would like to develop just a static application, that does not require any kind of access to the backend,
+   * you can use this flag to disable the login screen.
+   * NOTE: not all WebSDK components support this, some might require the user to be logged in and won't work.
+   */
+  noLogin?: boolean;
+  /**
+   * Allows to opt out of supporting/loading plugins for this application.
+   */
+  noPlugins?: boolean;
+  /**
+   * Allows to opt out of the version warning which is shown in the dev tools.
+   */
+  noVersionWarning?: boolean;
+  /**
+   * Link to the sensor app.
+   */
+  sensorAppOneLink?: string;
+  /**
+   * Allows to set the map layers. If not set, defaults to open street map layer.
+   */
+  mapLayers?: MapTileLayer[];
+  /**
+   * Allows to set default configurations on the maps.
+   */
+  mapConfig?: MapDefaultConfig;
+  /**
+   * The URL used to lookup geo coordinates for a user provided address via [nominatim API](https://nominatim.org/release-docs/develop/api/Search/).
+   * Can be set to empty to disable the find address feature on the location tab.
+   * Uses: `https://nominatim.openstreetmap.org/search?format=json&q={searchTerm}` if not set.
+   */
+  mapNominatimUrl?: string;
+  /**
+   * The name of the root element. By default c8y-bootstrap.
+   */
+  rootTagName?: string;
+  /**
+   * Hides possibility to create typed dashboards for assets (and groups). If true, typed dashboards can be created only for devices.
+   * It is true by default.
+   */
+  hideTypeDashboardForAssets?: boolean;
+  /**
+   * A matrix of versions indicating which versions of the application (key) are dependent on which version of a cumulocity component (API version and Web SDK version of the shell application currently supported, indicated by the value).
+   * The versions of the dependent components can be indicated by a semver range.
+   * ```json
+   * {
+   *  "1.0.0": {
+   *    "sdk": ">=1016.0.0 <1017.0.0",
+   *    "api": ">=1016.0.0 <1017.0.0"
+   *  },
+   *  "2.0.0": {
+   *    "sdk": "~1017.0.0",
+   *    "api": "~1017.0.0"
+   *  },
+   *  "3.0.0": {
+   *    "sdk": ">=1018.0.0",
+   *    "api": ">=1018.0.0"
+   *  },
+   * }
+   * ```
+   */
+  versioningMatrix?: VersioningMatrix;
+  /**
+   * Defines the type of refresh mechanism used for alarms in the application.
+   *
+   * - 'realtime': Utilizes a realtime mechanism for updating alarms.
+   * - 'interval': Utilizes HTTP polling at regular intervals to refresh the alarms.
+   *
+   * This setting allows to switch between realtime and interval-based refresh methods.
+   */
+  alarmsRefreshType?: 'interval' | 'realtime';
+}
+
+export interface MapDefaultConfig {
+  /**
+   * The default zoom level to set on each new map.
+   */
+  zoomLevel?: number;
+  /**
+   * The default center position of each new map.
+   */
+  center?: [number, number];
+}
+
+export interface MapTileLayer {
+  /**
+   * The layer url in the specific leaflet format.
+   */
+  layerUrl: string;
+  /**
+   * Additional options. Note this options are not typed as leaflet should not be by default included. The type from leaflet is L.TileLayerOptions.
+   */
+  options: any;
+  /**
+   * A label to show to the end user.
+   */
+  label: string;
+  /**
+   * Define the order of the layers to be shown to the user. Highest priority first.
+   */
+  priority?: number;
+  /**
+   * Indicates whether the layer is an overlay layer or an base layer. Default is false.
+   */
+  isOverlay?: boolean;
+}
+
+export interface RemotePlugins {
+  /**
+   * A key value pair, while the value is an array of modules to load and the
+   * key is the context path.
+   * ```js
+   * {
+   *    'cockpit': ['HomeDashboardModule', 'DataExplorerDashboard'],
+   *    'widget-package@1.0.0': ['ExtendedMapWidget']
+   * }
+   * ``
+   */
+  [key: string]: string[];
+}
+
+export interface PluginsExports {
+  /**
+   * The name of the plugin.
+   */
+  name: string;
+  /**
+   * The name of the Angular module class.
+   */
+  module: string;
+  /**
+   * The file path to the module typescript file.
+   */
+  path: string;
+  /**
+   * An short description about what the module does.
+   */
+  description?: string;
+  /**
+   * Allows to scope the plugin to certain applications.
+   * Default is undefined, which means every application can import this plugin.
+   *  - Use `self` to limit the plugin to the current application.
+   *  - The `global` is atm not used, but planned for allowing this plugin to all applications at the same time.
+   *  - The `self-optional` is used to add it as a possible plugin to the current application, without it being imported by default.
+   */
+  scope?: PluginsExportScopes;
+}
+
+/**
+ * Tells how a plugin is scoped.
+ *
+ * - `'self'`: Limit the plugin to the current application. It is imported by default.
+ * - `'global'`: Allows to add the plugin to a global scope, meaning it is imported to all applications at the same time.
+ *   This is not used at the moment but planned to be implemented in the new branding editor.
+ * - `'self-optional'`: Limit the plugin to the current application. The plugin is not imported by default.
+ * - `''`: Like undefined, the plugin is available for any private application.
+ */
+export type PluginsExportScopes = 'self' | 'global' | 'self-optional' | '';
+
+export interface CookieBannerConfiguration {
+  /** Here you can set the title of Cookie Banner */
+  cookieBannerTitle?: string;
+  /** Here you can set the Text of Cookie Banner */
+  cookieBannerText?: string;
+  /** Here you can set the policyUrl of Cookie Banner */
+  policyUrl?: string;
+}
+
+export interface CookiePreferencesConfiguration {
+  /** This category includes e.g. cookies related to logging in  */
+  required?: boolean | string;
+  /** This category includes e.g. tracking cookies  */
+  functional?: boolean | string;
+  /** This category includes e.g. cookies related to advertising  */
+  marketing?: boolean | string;
+}
+
+export interface LoginExtraLink {
+  url: string;
+  label: string;
+}
+
+export interface Icon {
+  class?: string;
+  url?: string;
+}
+
+export interface Docs {
+  /** Hide default links to documentation. */
+  noDefault?: boolean;
+  /** List of regex strings. Matching default docs URLs will be hidden. */
+  excludeDefault?: string[];
+  /** Additional links to be displayed. */
+  links?: Links[];
+}
+
+export interface Links {
+  /** Icon classes with `c8y-icon`, e.g. `c8y-icon c8y-icon-add-user` or `c8y-icon c8y-icon-device-connect`. */
+  icon: string;
+  label: string;
+  url: string;
+  type: 'doc' | 'quicklink';
+}
+
+export interface I18nExtra {
+  [langCode: string]: I18nExtraLangCode;
+}
+
+export interface I18nExtraLangCode {
+  [key: string]: string;
+}
+
+export interface Languages {
+  [langCode: string]: LanguagesLangCode;
+}
+
+export interface LanguagesLangCode {
+  name: string;
+  nativeName: string;
+  url?: string;
+}
+
+export interface BrandingCssVars {
+  [key: string]: string;
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export type * from './ApplicationOptions';