@brokerize/elements 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+# 1.4.1 (released 2025-09-08)
+
+-   `FIXED` In some environments, `crypto.randomUUID()` is not available. This was used for generating IDs in the previous version and is now replaced with `nanoid`
+
+# 1.4.0 (released 2025-08-27)
+
+-   `ADDED` the new component `Overview` which can replace `BrokerList`, `PortfolioTable` and `SessionsTable` in most applications
+-   `ADDED` An improved version of the `BrokerizeMain` component, which encapsulates `Overview` , `PortfolioView` and `OrderForm`.
+
+# 1.3.0 (released 2025-05-07)
+
+-   `ADDED` We have added the new function createCustomWebSocketClient to brokerize client, which allows customizing the WebSocke connection URL and token retrieval. The client can be passed to createAuthorizedContext so that the created client is used in all contexts (including brokerize elements components which rely on WebSockets).
+
+# 1.2.1 (released 2025-05-01)
+
+-   `FIXED` an issue where a relative API basePath lead to wrong WebSocket connection URLs.
+
 # 1.2.0 (released 2025-04-24)
 
 -   `ADDED` the option to pass a `reportingTag` for `createOrderForm`, `createChangeOrderForm` and `createCancelOrderForm`

package/README.md

@@ -101,6 +101,47 @@ const apiCtx = await this.client.createAuthorizedContext(authCtxCfg);
 and a theme can be provided in the same manner as in the [theming section](#theming).
 The above code is valid for Angular (and it's way of binding properties). Most frameworks allow to integrate custom elements similarly.
 
+## Overview
+
+A view for viewing the list of active brokerage sessions and portfolios and for managing session state (for example: enable/disable Session TAN). It also presents the list of available brokers for adding logins, so that it can be used as a starting point for logging in to brokers as well as a view for selecting the portfolio for trading.
+
+```typescript
+Brokerize.Elements.createOverview({
+	theme,
+	renderTo: resetRenderTo(),
+	authorizedApiContext: globalApiCtx,
+	onNavigate(portfolio) {
+		/* navigate to the selected portfolio view, e.g. by calling `createPortfolioView(...)` */
+		// showPortfolioView(portfolio.id);
+	},
+	onLogin({ brokerName }) {
+		/* open the broker login for the given brokerName. */
+		// Brokerize.Elements.createBrokerLoginForm(...)
+	}
+});
+```
+
+### web component
+
+```html
+<brokerize-overview ... />
+```
+
+| Property             | Description                                                                                                                                            | optional |
+| :------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: |
+| authorizedApiContext | Instance of `AuthorizedApiContext` from `@brokerize/client`                                                                                            | &#10060; |
+| theme                | You can use the <a href="https://app.brokerize.com/theming">brokerize theme designer</a> to build a theme JSON                                         | &#9989;  |
+| addFrame             | Add a "powered by brokerize" frame to the component                                                                                                    | &#9989;  |
+| supportLink          | Add a support link to the brokerize frame config, e.g. `{ emailSubject: 'Help needed for trading in XYZ app'}`                                         | &#9989;  |
+| confirmationStorage  | An implementation of a `ConfirmationStorage` which stores whether users have accepted legal terms. By default, this will try to use the `LocalStorage` | &#9989;  |
+
+### events
+
+| event    | Description                                                                         |
+| :------- | ----------------------------------------------------------------------------------- |
+| login    | is fired when the user has accepted the terms and conditions and clicked on `Login` |
+| navigage | is fired when the user navigates to a portfolio                                     |
+
 ## BrokerList
 
 A view that lets the user pick a broker for logging in. Selection of the broker as well as showing / accepting the terms and conditions of the given broker is handled inside the component.

package/dist/bundle.d.ts

@@ -3,7 +3,7 @@ import type { AuthorizedApiContext } from '@brokerize/client';
 import type { Brokerize } from '@brokerize/client';
 import type { BrokerizeError } from '@brokerize/client';
 import * as Client from '@brokerize/client';
-import type { Models } from '@brokerize/client';
+import { Models } from '@brokerize/client';
 
 export declare type BrokerizeBaseConfig = {
     	/**
@@ -53,6 +53,7 @@ export declare type BrokerizeElement = {
 
 export declare type BrokerizeElements = {
     	createBrokerizeMain: (cfg: BrokerizeMainConfig) => BrokerizeMainElement;
+    	createOverview: (cfg: OverviewConfig) => BrokerizeElement;
     	createBrokerList: (cfg: BrokerListConfig) => BrokerizeElement;
     	createBrokerLoginForm: (cfg: BrokerLoginFormConfig) => BrokerizeElement;
     	createOrderForm: (cfg: OrderFormConfig) => BrokerizeElement;
@@ -67,6 +68,7 @@ export declare type BrokerizeElements = {
     	createPortfolioView: (cfg: PortfolioViewConfig) => BrokerizeElement;
     	createModalHost: (cfg: ModalHostConfig) => BrokerizeElement;
     	createStylingUIExample: (cfg: StylingUIExampleConfig) => BrokerizeElement;
+    	createLoader: (cfg: LoaderConfig) => BrokerizeElement;
     	modalService: ModalService;
     	/**
      	 * Configure global settings for Brokerize Elements. The global configuration is shared across all instances of Brokerize Elements.
@@ -76,6 +78,11 @@ export declare type BrokerizeElements = {
      	 * @returns
      	 */
     	configure: (config: Partial<BrokerizeElementsGlobalConfiguration>) => void;
+    	/**
+     	 * The default theming token values. This can be used for building theme designers or inspecting themes
+     	 * together with `createStylingUIExample`.
+     	 */
+    	themingTokenDefaults: ThemeTokens;
 };
 
 export declare type BrokerizeElementsGlobalConfiguration = {
@@ -90,6 +97,8 @@ export declare type BrokerizeElementsGlobalConfiguration = {
     	assetsPath?: string;
 };
 
+export declare type BrokerizeLoaderVariant = 'brokerize' | 'spinner' | 'order' | 'loading';
+
 export declare type BrokerizeMainConfig = BrokerizeBaseConfig & {
     	onNavigationStateChange?: (state: any) => void;
     	useNavigation?: boolean;
@@ -104,11 +113,43 @@ export declare type BrokerizeMainElement = BrokerizeElement & {
 };
 
 export declare type BrokerizeNavigation = {
+    	/**
+     	 * @deprecated will be removed in a later version. Please us `navigateToPortfolio` instead.
+     	 */
     	NavigateToPortfolio: (portfolioId: string) => void;
+    	navigateToPortfolio: (portfolioId: string) => void;
+    	/**
+     	 * @deprecated will be removed in a later version. Please us `startOrderFlow` instead.
+     	 */
     	NavigateToOrderForm: (_isin: string, _initialOrderCreateValues: OrderFormInitialOrder) => void;
+    	/**
+     	 * Initiates the desired order flow. This may trigger a login redirect or directly show an order form, depending on
+     	 * which state the session is currently in.
+     	 *
+     	 * If the user is logged in to a broker, that one will be used and the brokerName parameter is ignored.
+     	 * If the user is logged in to a broker, but the desired portfolioId is not part of the list, a different portfolio may be used etc.
+     	 *
+     	 * @param orderFlowParams
+     	 * @returns
+     	 */
+    	startOrderFlow: (orderFlowParams: OrderFlowParameters) => void;
+    	/**
+     	 * @deprecated use NavigateToOverview instead
+     	 */
     	NavigateToChangeBroker: () => void;
+    	/**
+     	 * @deprecated use NavigateToOverview instead
+     	 */
     	NavigateToDepot: () => void;
+    	/**
+     	 * @deprecated use NavigateToOverview instead
+     	 */
     	NavigateToSessions: () => void;
+    	/**
+     	 * Shows the overview over current portfolios and sessions of the user. From there, they can navigate into one
+     	 * portfolio or add new broker logins.
+     	 */
+    	navigateToOverview: () => void;
 };
 
 /**
@@ -124,6 +165,10 @@ export declare type BrokerizeSummaryData = { title: string } & any;
 export declare type BrokerListConfig = {
     	onLogin: (data: { brokerName: string }) => void;
     	confirmationStorage?: ConfirmationStorage;
+    	/** brokerize-internal */
+    	disclaimerPrefixHtml?: string;
+    	/** brokerize-internal */
+    	infoPreamble?: string;
 } & BrokerizeBaseConfig;
 
 export declare type BrokerLoginFormConfig = {
@@ -379,9 +424,18 @@ export declare type InputConfig = {
 
 export declare type LinkTarget = {
     	type: 'portfolio';
+    	portfolio?: Models.Portfolio;
     	portfolioId: string;
 };
 
+export declare type LoaderConfig = {
+    	variant?: BrokerizeLoaderVariant;
+    	alignment?: string;
+    	overlay?: boolean;
+    	repeat?: boolean;
+    	size?: number;
+} & BrokerizeBaseConfig;
+
 export declare type LoginFormConfig = {
     	onGuestLogin: () => void;
     	client: Brokerize;
@@ -425,6 +479,25 @@ export declare type openExternalLinkCallback = (url: string, target?: string, wi
 
 export declare type OrderDirection = 'asc' | 'desc';
 
+export declare type OrderFlowParameters = {
+    	/**
+     	 * The security to open the order form for.
+     	 */
+    	security?: Models.Security;
+    	/**
+     	 * The broker to prefer, if it is available.
+     	 */
+    	brokerName?: string;
+    	/**
+     	 * The portfolioId to prefer, if it is available.
+     	 */
+    	portfolioId?: string;
+    	/**
+     	 * The initial order values to show.
+     	 */
+    	initialOrderCreateValues?: OrderFormInitialOrder;
+};
+
 export declare type OrderFormConfig = {
     	portfolioId: string;
     	/**
@@ -475,10 +548,21 @@ export declare type OrderFormConfig = {
      	 * If custom quotes should be shown in the order form, provide an implementation of `SecurityQuotesProvider`.
      	 */
     	quotesProvider?: SecurityQuotesProvider;
+    	onNavigate?: (linkTarget: LinkTarget) => void;
+    	onChangedPreparedTrade?: (preparedTrade: Models.PreparedTrade) => void;
     	/**
      	 * Optional `reportingTag` to send with order creates. ReportingTags appear in order reports.
      	 */
     	reportingTag?: string;
+    	/**
+     	 * Set this to `true` to allow users select a different portfolio inside the widget.
+     	 */
+    	allowChangePortfolio?: boolean;
+    	/**
+     	 * Called if the user wants to add a new broker login. This should navigate to the overview.
+     	 * Only available if allowChangePortfolio is true.
+     	 */
+    	onAddBrokerLogin?: () => void;
 } & BrokerizeBaseConfig;
 
 export declare type OrderFormInitialOrder = Partial<
@@ -500,8 +584,13 @@ export declare type OrderFormInitialOrder = Partial<
 >;
 
 export declare type OrderReceiptConfig = {
-    	orderId: string;
-    	onNavigate: (linkTarget: LinkTarget) => void;
+    	orderId?: string;
+    	orderData?: ReceiptData;
+    	/**
+     	 * `true` if the receipt is shown in response to an order creation.
+     	 */
+    	isOrderConfirmation?: boolean;
+    	onNavigate?: (linkTarget: LinkTarget) => void;
 } & BrokerizeBaseConfig;
 
 export declare type OrderTableConfig = {
@@ -512,6 +601,11 @@ export declare type OrderTableConfig = {
     	onShowReceipt: ({ orderId }: { orderId: string }) => void;
 } & BrokerizeBaseConfig;
 
+export declare type OverviewConfig = BrokerizeBaseConfig & {
+    	onNavigate: (portfolio: Models.Portfolio) => void;
+    	onLogin: (data: { brokerName: string }) => void;
+};
+
 export declare type PortfolioTableConfig = {
     	hideInactivePortfolios?: boolean;
     	onNavigate: (portfolio: Models.Portfolio) => void;
@@ -519,7 +613,16 @@ export declare type PortfolioTableConfig = {
 
 export declare type PortfolioViewConfig = {
     	portfolioId: string;
-    	onBuy: (opts: { security: Models.Security; isin: string }) => void;
+    	/**
+     	 * Set this to `true` to allow users select a different portfolio inside the widget.
+     	 */
+    	allowChangePortfolio?: boolean;
+    	/**
+     	 * Called if the user wants to add a new broker login. This should navigate to the overview.
+     	 * Only available if allowChangePortfolio is true.
+     	 */
+    	onAddBrokerLogin?: () => void;
+    	onBuy: (opts: { security: Models.Security; isin: string; availableSize?: number }) => void;
     	onSell: (opts: { security: Models.Security; isin: string; availableSize: number }) => void;
     	onCancelOrder: (opts: { orderId: string }) => void;
     	onChangeOrder: (opts: { orderId: string }) => void;
@@ -584,9 +687,7 @@ export declare type SecurityQuotesProviderOpts = {
 
 export declare type SecurityQuoteSubscription = { unsubscribe: () => void };
 
-export declare type SessionsTableConfig = {
-    	onEnableSessionTan: (opts: { sessionId: string }) => void;
-} & BrokerizeBaseConfig;
+export declare type SessionsTableConfig = BrokerizeBaseConfig;
 
 export declare type SessionTanFormConfig = {
     	sessionId: string;
@@ -602,7 +703,8 @@ export declare type ShowToast = (opts: ToastOptions) => void;
 
 export declare type StylingUIExampleConfig = {
     	theme: Theme;
-} & BrokerizeBaseConfig;
+    	renderTo: HTMLElement;
+};
 
 export declare type SupportLink = {
     	emailSubject: string;
@@ -656,6 +758,8 @@ export declare type ThemeTokens = {
     	'zl-box-shadow-md'?: string;
     	'zl-box-shadow-sm'?: string;
     	'zl-box-shadow-xl'?: string;
+    	'zl-broker-select-background-color'?: string;
+    	'zl-broker-select-border-color'?: string;
     	'zl-btn-active-background-color'?: string;
     	'zl-btn-active-background-image'?: string;
     	'zl-btn-background-color'?: string;
@@ -665,6 +769,15 @@ export declare type ThemeTokens = {
     	'zl-btn-border-style'?: string;
     	'zl-btn-border-width'?: string;
     	'zl-btn-default-color'?: string;
+    	'zl-btn-error-active-background-color'?: string;
+    	'zl-btn-error-background-color'?: string;
+    	'zl-btn-error-border-color'?: string;
+    	'zl-btn-error-color'?: string;
+    	'zl-btn-error-focus-color'?: string;
+    	'zl-btn-error-hover-background-color'?: string;
+    	'zl-btn-error-hover-color'?: string;
+    	'zl-btn-error-muted-color'?: string;
+    	'zl-btn-error-outlined-color'?: string;
     	'zl-btn-focus-background-image'?: string;
     	'zl-btn-focus-color'?: string;
     	'zl-btn-hover-background-color'?: string;
@@ -682,6 +795,24 @@ export declare type ThemeTokens = {
     	'zl-btn-sm-font-size'?: string;
     	'zl-btn-sm-padding-x'?: string;
     	'zl-btn-sm-padding-y'?: string;
+    	'zl-btn-success-active-background-color'?: string;
+    	'zl-btn-success-background-color'?: string;
+    	'zl-btn-success-border-color'?: string;
+    	'zl-btn-success-color'?: string;
+    	'zl-btn-success-focus-color'?: string;
+    	'zl-btn-success-hover-background-color'?: string;
+    	'zl-btn-success-hover-color'?: string;
+    	'zl-btn-success-muted-color'?: string;
+    	'zl-btn-success-outlined-color'?: string;
+    	'zl-btn-warning-active-background-color'?: string;
+    	'zl-btn-warning-background-color'?: string;
+    	'zl-btn-warning-border-color'?: string;
+    	'zl-btn-warning-color'?: string;
+    	'zl-btn-warning-focus-color'?: string;
+    	'zl-btn-warning-hover-background-color'?: string;
+    	'zl-btn-warning-hover-color'?: string;
+    	'zl-btn-warning-muted-color'?: string;
+    	'zl-btn-warning-outlined-color'?: string;
     	'zl-card-background-color'?: string;
     	'zl-card-border-color'?: string;
     	'zl-card-border-radius'?: string;
@@ -747,6 +878,7 @@ export declare type ThemeTokens = {
     	'zl-default-border-width'?: string;
     	'zl-default-box-shadow'?: string;
     	'zl-default-font-size'?: string;
+    	'zl-default-line-height'?: string;
     	'zl-default-link-color'?: string;
     	'zl-default-link-decoration'?: string;
     	'zl-default-padding-x'?: string;
@@ -819,6 +951,9 @@ export declare type ThemeTokens = {
     	'zl-input-with-dropdown-border-bottom-right-radius'?: string;
     	'zl-input-with-dropdown-border-top-left-radius'?: string;
     	'zl-input-with-dropdown-border-top-right-radius'?: string;
+    	'zl-kebab-menu-box-shadow'?: string;
+    	'zl-kebab-menu-max-width'?: string;
+    	'zl-kebab-menu-padding'?: string;
     	'zl-keyfigures-font-size'?: string;
     	'zl-keyfigures-gap-x'?: string;
     	'zl-keyfigures-gap-y'?: string;
@@ -830,6 +965,11 @@ export declare type ThemeTokens = {
     	'zl-label-color'?: string;
     	'zl-label-font-size'?: string;
     	'zl-label-font-weight'?: string;
+    	'zl-line-height-base'?: string;
+    	'zl-line-height-lg'?: string;
+    	'zl-line-height-md'?: string;
+    	'zl-line-height-sm'?: string;
+    	'zl-line-height-xs'?: string;
     	'zl-link-underline-offset'?: string;
     	'zl-listbox-background-color'?: string;
     	'zl-listbox-border-color'?: string;
@@ -842,7 +982,6 @@ export declare type ThemeTokens = {
     	'zl-loader-contrast-color'?: string;
     	'zl-logo-margin'?: string;
     	'zl-logo-max-width'?: string;
-    	'zl-overlay-backdrop-opacity'?: string;
     	'zl-modal-background-color'?: string;
     	'zl-modal-background-image'?: string;
     	'zl-modal-close-offset'?: string;
@@ -902,6 +1041,23 @@ export declare type ThemeTokens = {
     	'zl-order-toggle-sell-selected-background-color'?: string;
     	'zl-order-toggle-sell-selected-color'?: string;
     	'zl-order-toggle-text-align'?: string;
+    	'zl-overlay-backdrop-opacity'?: string;
+    	'zl-panel-background-color'?: string;
+    	'zl-panel-border-color'?: string;
+    	'zl-panel-color'?: string;
+    	'zl-panel-disbled-color'?: string;
+    	'zl-panel-error-background-color'?: string;
+    	'zl-panel-error-border-color'?: string;
+    	'zl-panel-error-color'?: string;
+    	'zl-panel-info-background-color'?: string;
+    	'zl-panel-info-border-color'?: string;
+    	'zl-panel-info-color'?: string;
+    	'zl-panel-success-background-color'?: string;
+    	'zl-panel-success-border-color'?: string;
+    	'zl-panel-success-color'?: string;
+    	'zl-panel-warning-background-color'?: string;
+    	'zl-panel-warning-border-color'?: string;
+    	'zl-panel-warning-color'?: string;
     	'zl-popup-background-color'?: string;
     	'zl-popup-color'?: string;
     	'zl-popup-font-weight'?: string;