npm package: @munichremarkets/simulator-index-linked
Latest version: 2.0.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.


# Munich Re Markets Simulator - Index-Linked Widget


This package provides the _Simulator - Index-Linked_ widget by Munich Re Markets for integration into your website.

## Installation

If you use NPM as a package manager, run

```shell
  npm install --save @munichremarkets/simulator-index-linked
```

And if you use Yarn:

```shell
  yarn add @munichremarkets/simulator-index-linked
```



## Integration

The Simulator - Index-Linked widget provides a (plain JavaScript) rendering API in the form of the `renderSimulatorIndexLinked` function
that is used to display the widget on the page and pass data to the widget.

### Importing from NPM

The Simulator - Index-Linked package contains JavaScript (ES5) code in both ECMAScript and UMD (Universal Module Definition)
module formats, so you need to use a bundler that supports either of these formats, such as Webpack or Rollup. Using
ES6-style imports, your code might look like this:

```javascript
import { renderSimulatorIndexLinked } from '@munichremarkets/simulator-index-linked';
```

TypeScript declaration files (`.d.ts`) are also included in the package, providing typings and enhanced IDE support for
the rendering API.


### Rendering the widget

In order to render the widget, you need to invoke the `renderSimulatorIndexLinked` rendering function that is made available as
described above. The following data needs to be provided when invoking the rendering function:

-   A target DOM element (typically a `<div>` element) into which the widget should be rendered
-   A configuration object providing data to the widget, see section "Configuring the widget" below

For example, a call to the rendering function might look like this (ES6):

```javascript
const target = document.getElementById('widget-target');

renderSimulatorIndexLinked(target, {
    /* configuration data, see below */
});
```

Please make sure to invoke the rendering function after the DOM has been loaded, e.g. by putting the call into
a `<script>` tag at the end of the `<body>` or into a `DOMContentLoaded` event handler.

-   **Note:** You need to make sure that the `process.env` object is available (not just `process.env.NODE_ENV`), e.g.
    using Webpack's [Define Plugin](https://webpack.js.org/plugins/define-plugin/).

### Unmounting the widget

The rendering function returns a cleanup function that can be used to unmount the widget like this:

```javascript
const target = document.getElementById('widget-target');

const unmountWidget = renderSimulatorIndexLinked(target, {
    /* configuration data, see below */
});

/* use `unmountWidget` e.g. in an event listener */
```

### Configuring the widget

The configuration object passed to `renderSimulatorIndexLinked` can contain the following properties (example values):

```
{
    // Whether to include widget-scoped Bootstrap 4.x CSS into the page
    // Optional, default: false
    // Set this to `true` if you are not already using Bootstrap on your website
    includeBootstrap4Css: true,

    // Locale to use for localized texts
    // Mandatory
    // Currently available locales: Locale.DeDe, Locale.EnUs
    locale: Locale.DeDe,

    // Configurator for default and possible values of the simulator
    // Mandatory
    setupValues: {
        // Values to use in single premium selection
        // In full Euro
        // Mandatory
        singlePremium: {
            default: 10000,
            minimum: 1000,
            maximum: 100000,
        },

        // Values to use in contract term selection
        // In years
        // Mandatory
        // Note: Only contract terms of up to 12 years are supported
        contractTerm: {
            default: 10,
            minimum: 1,
            maximum: 12,
        },

        // Values to use in guaranteeLevel selection
        // As percentages between 0 and 1
        // Mandatory
        guaranteeLevel: {
            default: 0.9,
            possibleLevels: [0.8, 0.9],
        },

        // Values to use for the simulation calculation
        // Mandatory
        insurerParams: {
            // Assumed actual general account yearly interest rate
            // As percentages between 0 and 1
            // Mandatory
            assumedActualGeneralAccountYearlyInterestRate: {
                conservative: 0.009,
                moderate: 0.015,
                optimistic: 0.025,
            },

            // Guaranteed general account yearly interest rate
            // As percentage between 0 and 1
            // Mandatory
            guaranteedGeneralAccountYearlyInterestRate: 0.009,

            // One off sales and administrative costs
            // As percentage between 0 and 1
            // Mandatory
            oneOffSalesAndAdministrativeCosts: 0.01,
        },
    },

    // Custom texts per locale
    // Optional - if not specified, default texts are used
    textOverrides: {
        'simulatorIndexLinked.general.title': {
            // Texts can be provided in any supported locale (see `locale` option)
            [Locale.DeDe]: 'Simulator - Index-Linked',
            [Locale.EnUs]: 'Simulator - Index-Linked',
        },
    },
}

```



The following things should be considered in order to ensure that the widget works as intended.

**Note:** Providing data that does not adhere to the documented API of the widget may lead to unexpected behavior or the
widget not working altogether.

### Text override mechanism

Some texts that are displayed by the widget can be overridden by providing the `textOverrides` option in the
configuration object. It expects an object in the form of

```
{
    'some.overridable.key': {
        [Locale.DeDe]: 'Some German text',
        [Locale.EnUs]: 'Some English text (US)',
        [Locale.EnGb]: 'Some English text (GB)',
    },
    'some.other.key': { /* ... */ }
}
```

where `some.overridable.key` is a localization key specified by the widget.

**Note:** The override mechanism is entirely optional. If it is omitted, default texts are used instead.

#### Semantic markup

Some texts can contain basic semantic HTML markup that is sanitized before displaying. The following tags are allowed
and will be displayed as bold, italic, underlined, etc.: `strong`, `b`, `em`, `i`, `u`, `br`, `p`.

**Note:** HTML tags cannot contain attributes. If provided anyway, they are removed during sanitization (
e.g. `<em class="some-classname">some text</em>` will be converted to `<em>some text</em>`).

#### Interpolation

In some cases, texts might need to include dynamic values (e.g. monetary values or percentages). Such values can be
referenced in the text using `{{someVariable}}`, where `someVariable` is a predefined name specific to the respective
text key and will be replaced with the actual value during runtime.

#### Empty default text

In some cases default texts might be empty, which will cause the enclosing markup element (e.g. an information icon with
accompanying text label) to purposefully not be displayed in the widget. This is a mechanism to remove markup elements
entirely when the text that they usually display is missing. In these cases, a text override can be supplied to make the
element visible again.


### Mandatory and optional fields in the configuration

-   When using TypeScript, your IDE should automatically indicate which fields are mandatory/optional via the provided
    typings.
-   When using plain JavaScript, please refer to the section above regarding mandatory/optional fields.
-   The widget will perform a schema validation on the provided configuration and will fail to render if the validation
    fails. In this case you can then find additional information on why the validation failed in the console of your
    browser.

### Providing enumeration values in the configuration


Enumerations can be directly imported from the widget library. This works with both plain JavaScript and TypeScript. For
instance, the `Locale` enumeration can be used like this:

```javascript
import {renderSimulatorIndexLinked, Locale} from '@munichremarkets/simulator-index-linked';

const target = document.getElementById('widget-target');
renderSimulatorIndexLinked(target, {locale: Locale.En_US, ...});
```


Although other ways of providing an enumeration value are technically possible (e.g. numerical or string values), it is
considered improper usage and may stop working at any point.




## Recommendations

-   Do not use a side navigation besides the widget.
-   Do not implement the widget in modals.
-   The respective widget should take as much height as it needs.



## Styling

### Framework

The Simulator - Index-Linked widget uses version 4.x of the Bootstrap framework for styling. When integrating the widget into your
website, you need to do different things depending on whether your website uses Bootstrap, too:

#### Case 1: Your website uses Bootstrap

In this case, Bootstrap CSS rules are already present on your website and all the Bootstrap theme colors defined by your
website will automatically be used by the widget. Note that the supported range of Bootstrap versions is from 4.2 to 4.6
(inclusive).

#### Case 2: Your website does not use Bootstrap

In this case, you are required to set the `includeBootstrap4Css` flag to `true` when invoking the widget rendering
function, so that the Bootstrap 4.x CSS rules shipped with the widget are included on your page. Those CSS rules will
not affect the appearance of elements outside the widget because they are scoped to the `.sri-widget` CSS class that is
assigned to a DOM element the widget is rendered into.

### Adaptation of styling

By default, the styling of the widget automatically adapts to the styling of your website to a certain extent. However,
you can still customize the appearance if necessary.

#### Automatic styling

##### Fonts

Since the widget does not define its own font, any font you define in the DOM tree above the widget will automatically
be used within the widget.

##### Spacings

Font sizes and most of the spacings are defined in units of `rem` (root `em`), so these sizes will automatically be set
relative to the font size of your website's `<body>` element.

##### Width

The widget will automatically fill the full width of its parent element.

##### Theming

###### Primary theming API: Overriding Bootstrap theme colors & CSS variables

Regardless of whether you are providing a custom-themed Bootstrap or not, certain colors (_SRI colors_) need to be
customized. The minimal set of CSS variables that should be overridden are `emphasis`, `element`, and the shades
of `primary`, `secondary` and `emphasis`:

```
primary-[50-900]
secondary-[50-900]
emphasis
emphasis-[50-900]
element-[0-23]
element-other
```

The `element-*` colors are used within indicators and charts (funds, categories, ...). The `element-other` color is used
specifically for those instances where it's necessary to display an "_Other_" category in an indicator or chart.

By default, all additional colors are derived from those colors so overriding them should already provide a good
baseline for theming.

**Case 1: Your website uses Bootstrap**

_Bootstrap theme colors:_ Bootstrap components used throughout the Munich Re Markets widgets will be styled correctly,
CSS variables for those customized colors are expected to be available on `:root`. This should require no further
action.

**Case 2: Your website does not use Bootstrap**

_Bootstrap theme colors:_ The CSS variables referring to the Bootstrap theme colors need to be overridden:

```
--primary
--secondary
--success
--danger
--warning
--info
--light
--dark
```

To make sure that your settings for these variables take precedence over the defaults defined by the widget, use the CSS
selector `.sri-widget.sri-external` like this:

```css
.sri-widget.sri-external {
    --primary: red;
}
```

**Note:**

-   Bootstrap internally uses SCSS variables, which are only present at build time. Since you will use the Bootstrap CSS
    rules shipped with the widget if you don't provide your own, components provided by Bootstrap will not be themed
    properly by just overriding the CSS variables. Also, classes like `.text-primary`, `.bg-primary` etc. will use wrong
    color values. In those cases the according CSS classes have to be overridden individually (see next section).
-   Any style overrides except changing Bootstrap theme colors may stop working at any point and hence need to be
    thoroughly tested on every upgrade.

###### Secondary theming API: Overriding CSS classes

You can override each style of the application via CSS classes individually. Therefore, it is important to know the
basic markup of the widget, which looks like this:

```html
<!-- Passed into the rendering function by your website -->
<div>
    <!-- Created by the rendering function -->
    <div>
        <div class="sri-widget sri-external">
            <div class="sri-simulator-index-linked">
                <!-- Widget content -->
            </div>
        </div>
    </div>
</div>
```

If you want to style an element within the main content of the widget, prefix all CSS rules
with `.sri-widget.sri-external` to ensure that your CSS rule is more specific than the ones shipped with the widget and
hence overrides the latter. For example, to style a button (`.sri-btn`), use a CSS rule like this:

```css
.sri-widget.sri-external .sri-btn {
    /* ... */
}
```

If you use other widgets on the same page and need to scope a rule specifically to the Simulator - Index-Linked widget,
additionally include the widget-specific class like this:


```css
.sri-widget.sri-external.sri-simulator-index-linked .sri-btn {
    /* ... */
}
```


There is one special case: Some elements need to be rendered directly into the `<body>` of your website to ensure that
they cover other elements, e.g. modal dialogs and tooltips. For these elements, the markup looks like this:

```html
<div class="sri-widget sri-external sri-simulator-index-linked sri-modal">
    <!-- Modal content -->
</div>
```

In this case, you can override styles within the modal using CSS rules like this:


```css
.sri-widget.sri-external.sri-simulator-index-linked.sri-modal .sri-btn {
    /* ... */
}
```


**Notes:**

-   Use `!important` for rules originating from Bootstrap. This is because Bootstrap already declares all rules
    as `!important`, so your rules need to be `!important`, too, in order to override the Bootstrap rules.
-   Any style overrides except changing Bootstrap theme colors may stop working at any point and hence need to be
    thoroughly tested on every upgrade.

##### Print view

In the print view, you might want to hide certain elements on your page (e.g. header and footer), reduce page margins
etc. You can do this using a media query like this:

```css
@media print {
    header {
        display: none !important;
    }
}
```

## Recommendations for mobile viewports

Viewports in the "Extra small" (`xs`) and "Small" (`sm`) ranges of the responsive breakpoints defined by Bootstrap, i.e.
narrower than `768px`, are considered "mobile" viewports and larger ones are considered "desktop" viewports.

Although the Simulator - Index-Linked widget is generally responsive across all breakpoints, there are significant changes in
layout between mobile and desktop viewports. Hence it is recommended to test your website in both variants.

## Browser support

The following browsers are supported:

-   Chrome (latest version)
-   Firefox (latest version)
-   Safari on macOS and iOS (latest two major versions)