GitHub Homepage React Spectrum Libraries Legal Notice

@wuespace/telestion-client-types

Install using

npm install @wuespace/telestion-client-types

Exported Members

You can access these members by importing the module:

import { member } from '@wuespace/telestion-client-types';

JsonSerializable

type JsonSerializable

Alias for: | null | number | string | boolean | { [key: string]: JsonSerializable | undefined } | Array<JsonSerializable>

a type that only allows JSON serializable data

AbstractRouting

interface AbstractRouting

Defines a generic routing interface for a Page component.

Properties

path

Type: string

Describes the path of the Page component.

The Page will be rendered if the application path resolves to the specified path.

exact ?

Type: boolean

When it is true the Path will only match if the application route is exactly the same as the specified path above.

AbstractRedirect

interface AbstractRedirect extends AbstractRouting

Defines a generic routing interface with an additional redirect specifier for a Page component.

Properties

redirectPath

Type: string

Describes the path the application will be redirected if the routing type does not match current application state.

AdditionalRedirect

interface AdditionalRedirect extends AbstractRedirect

Specifies an additional redirect which will add a route to the application when the application path matches the application are redirected to the specified path.

Properties

last

Type: boolean

If it is true the additional redirect will be inserted after all registered routes in the [@wuespace/telestion-client-core#Pages | Pages renderer component](#@wuespace/telestion-client-core#Pages | Pages renderer component) otherwise it will be directly attached after the routing definition of the component.

DefaultRouting

interface DefaultRouting extends BaseRouting

Specifies the default type of routing for a Page component.

It not depends on the application state and will always be reachable under the given [AbstractRouting.path | path](#AbstractRouting.path | path).

Properties

type

Type: 'default'

No docs provided

UnAuthRouting

interface UnAuthRouting extends BaseRouting,AbstractRedirect

Specifies an unauthorized type of routing for a Page component.

The Page will only be rendered if the user is unauthorized (or logged out) in the application otherwise the app will be redirected to the given AbstractRedirect.redirectPath.

Properties

type

Type: 'unAuth'

No docs provided

AuthRouting

interface AuthRouting extends BaseRouting,AbstractRedirect

Specifies an authorized type of routing for a Page component.

The Page will only be rendered if the user is authorized (or logged in) in the application otherwise the app will be redirected to the given AbstractRedirect.redirectPath.

Properties

type

Type: 'auth'

No docs provided

Routing

type Routing

Alias for: DefaultRouting | UnAuthRouting | AuthRouting

Defines an object type for routing information of a Page in Telestion Client. It can be based on the application route and state and is important for Pages used in the [@wuespace/telestion-client-core#Pages | Pages renderer component](#@wuespace/telestion-client-core#Pages | Pages renderer component).

BasePropType

type BasePropType

Alias for: JsonSerializable

Defines the basic prop-type of Widget component.

GenericProps

interface GenericProps

Specifies the most generic properties that a Widget component can have.

@see:

@see:

@example:

Initialization of basic, advanced and invalid properties

const myProps: GenericProps = {
	basic: 'Where is the box?',
	advanced: {
		part1: 'Test it!',
		part2: false,
		part3: 3.14
	},
	invalid: () => console.log('Ohh...') // not allowed
};

Properties

GenericComponent

type GenericComponent < P : Record<string, unknown> = Record<string, unknown> >

Alias for: (props: P) => ReactNode

Specifies the most generic type a Widget component and a ConfigControls component can have.

@typeParam:

P - additional props for the Widget renderer component (see example below)

@see:

@see:

@example:

Common usage

import { ReactNode } from 'react';

interface WidgetProps extends GenericProps {
	type: 'basic' | 'advanced';
}

interface RendererProps extends BaseRendererProps<WidgetProps> {}

function Widget({ title, type }: RendererProps): ReactNode {
	return (
		<div>
			<p>Title: {title}</p>
			<p>Type: {type}</p>
		</div>
	);
}

export const myWidget: Widget<WidgetProps> = {
	name: 'My Widget',
	Widget: Widget
};

BaseRendererProps

type BaseRendererProps < P : GenericProps = GenericProps >

Alias for: P

These are the most basic renderer props that a Widget renderer component can have. It is extensible via a generic type to add more props to the Widget renderer component.

@typeParam:

P - additional props for the Widget renderer component

@see:

@see:

@see:

@example:

A very simple widget

import { ReactNode } from 'react';

function Widget({ title, type }: BaseRendererProps): ReactNode {
	return <p>Title: {title}</p>;
}

export const verySimpleWidget: Widget<WidgetProps> = {
	name: 'Very simple Widget',
	Widget: Widget
};

@example:

Extended widget

import { ReactNode } from 'react';

interface WidgetProps extends GenericProps {
	type: 'basic' | 'advanced';
}

interface RendererProps extends BaseRendererProps<WidgetProps> {}

function Widget({ type }: RendererProps): ReactNode {
	return (
		<div>
			<p>Type: {type}</p>
		</div>
	);
}

export const myWidget: Widget<WidgetProps> = {
	name: 'My Widget',
	Widget: Widget
};

BaseConfigControlsProps

interface BaseConfigControlsProps < P : GenericProps = GenericProps > extends Record<string, unknown>

These are props for the ConfigControls widget. that a Widget renderer component can have. It is extensible via a generic type to add more props that are also used at the Widget renderer component.

@typeParam:

P - additional props for the Widget renderer component

@see:

@see:

@see:

@example:

Very simple ConfigControls

import { ReactNode } from 'react';

interface WidgetProps extends GenericProps {
	value: string;
}

interface RendererProps extends BaseRendererProps<WidgetProps> {}

interface ConfigControlsProps extends BaseConfigControlsProps<WidgetProps> {}

function Widget({ value }: RendererProps): ReactNode {
	return <p>Value: {value}</p>;
}

function ConfigControls({  }

Properties

currentProps

Type: P

the current props values of the widget which can be changed with [BaseConfigControlsProps.onUpdate | onUpdate](#BaseConfigControlsProps.onUpdate | onUpdate)

onUpdate

Type: (newProps: Partial<P>) => void

Updates the values of the props of the widget.

@param:

newProps - new props that are merged or replaced with the current props to build the new props for the widget to use

@example:

Update the props in a ConfigControls component

function ConfigControls({
  currentProps, onUpdate
}: ConfigControlsProps): ReactNode {
  // local state to not "flood" global store with changes (performance)
  const [value, setValue] = useState(currentProps.value);

  return (
    <div>
      <input type="text" value={value} onChange={event => setValue(event.target.value)} />
      <button onClick={() => onUpdate({ value })} />
    </div>
  );
}

Widget

interface Widget < P : GenericProps = GenericProps >

An "entire" widget definition ready to export and use. It contains a name for reference, a Widget component that will be rendered and an optional ConfigControls component to change Widget component props.

@typeParam:

P - additional props for the Widget renderer component

@see:

@see:

@see:

@example:

A very simple widget

import { Widget } from './widget';
import { ConfigControls } from './config-controls';

export const myWidget: Widget = {
	name: 'My Awesome Widget',
	Widget: Widget,
	ConfigControls: ConfigControls
}

Properties

name

Type: string

the name of the widget

It is a selector to reference the widget.

title ?

Type: string

The full title of the widget which are displayed in the settings page and in the widget selector.

If the title is not defined, the name is used as a fallback.

version

Type: string

The version of the widget. Different values resulting in different stored properties in the widget renderer. Useful, when you have a breaking change in your widget props.

Widget

Type: GenericComponent<BaseRendererProps<P>>

the Widget component implementation as React Component

ConfigControls ?

Type: GenericComponent<BaseConfigControlsProps<P>>

the ConfigControls component implementation as React Component

WidgetDefinition

interface WidgetDefinition

Defines a widget placeholder in a dashboard container.

This is done via the [https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system](#https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system).

@see:

@see:

@see:

@example:

A very simple widget definition for a dashboard

const myWidgetDef: WidgetDefinition = {
	width: 2,
	height: 4,
	widgetName: 'myWidget',
	initialProps: {
		value: 'The Box'
	}
}

Properties

id

Type: string

A unique identifier which represents this specific widget.

width

Type: number

the width of the widget in columns

This is done via the CSS Grid system.

height

Type: number

the number of columns the widget has space in the container

This is done via the CSS Grid system.

widgetName

Type: string

the number of row the widget has space in the container

@see:

initialProps ?

Type: GenericProps

the initial props for the Widget component

if the initial props are not defined they are undefined

Dashboard

interface Dashboard

Defines a dashboard which renders given widgets in defined positions.

The dashboard is a structural container which sets the boundaries for the widgets to fit into. This is done via the [https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system](#https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system).

@see:

@see:

@example:

A very simple dashboard

const myDashboard: Dashboard = {
	title: 'My Dashboard',
	columns: 4,
	rows: 4,
	widgets: [
		{
			width: 2,
			height: 2,
			widgetName: 'myWidget'
		}
	]
};

Properties

title

Type: string

the title of the dashboard

It will be visible in the application and selectable by the user.

columns

Type: number

the number of columns in the dashboard container

It is important for the spacing of the widget in the dashboard container. See [https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system](#https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system) for more information.

rows

Type: number

the number of rows in the dashboard container

It is important for the spacing of the widget in the dashboard container. See [https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system](#https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system) for more information.

widgets

Type: WidgetDefinition[]

widgets associated to the dashboard container

These widgets will be arranged in the container based on the columns and rows of the dashboard and the width and height of the widgets. See [https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system](#https://css-tricks.com/snippets/css/complete-guide-grid/ | CSS Grid system) for more information.

Username

type Username

Alias for: string

A type definition for a username in a user configuration.

@see:

UserInformation

interface UserInformation

User information mapped to a username and stored in a user configuration.

@see:

@see:

Properties

dashboards

Type: Array<Dashboard>

The dashboards associated to the user.

@see:

UserConfig

type UserConfig

Alias for: Record<Username, UserInformation>

Describes an entire user configuration. It is a map between the username and its stored information. When the user is logged in, typically the dashboard page will render these definitions for the logged in username.

@see:

@example:

A very simple user dashboard association

const userConfig: UserConfig = {
	'Alice': {
		dashboards: [
			{
				title: 'My awesome dashboard',
				columns: 4,
				rows: 4,
				widgets: [
					{
						width: 2,
						height: 2,
						widgetName: 'myWidget'
						initialProps: {
							value: 'TheBox'
						}
					}
				]
			}
		]
	}
}

SignInResult

interface SignInResult extends BaseResult

Result of a sign in process commonly returned from a sign in function of an authenticator.

@see:

@see:

@example:

Analyze sign in result

const authenticator: Auth = new SomeAuth(); // implements Auth

authenticator.signIn('http://localhost:9870/bridge', 'alice', '12345')
	.then(signInRes => {
		console.log(`User ${signInRes} signed in`);
		if (signInRes.reason) {
			console.log(`Because ${signInRes.reason}`);
		}
	}

Properties

type

Type: 'signIn'

No docs provided

user

Type: string

the name of the user who is authenticated

@see:

eventBusUrl

Type: string

the url of the eventbus server to connect to after authentication

@see:

SignOutResult

interface SignOutResult extends BaseResult

Result of a sign out process commonly returned from a sign out function of an authenticator.

@see:

@see:

@example:

Analyze sign in result

const authenticator: Auth = new SomeAuth(); // implements Auth

// maybe some sign in before

authenticator.signOut()
	.then(signOutRes => {
		console.log(`Signed out`);
		if (signOutRes.reason) {
			console.log(`Because ${signOutRes.reason}`);
		}
	}

Properties

type

Type: 'signOut'

No docs provided

AuthResult

type AuthResult

Alias for: SignInResult | SignOutResult

an authentication result commonly returned from an authenticator sign in or sign out function.

It can be a sign in result or a sign out result based on the current authentication state.

@see:

@see:

@see:

Auth

interface Auth

A definition for an authenticator.

It may be used in the @wuespace/telestion-client-core#useAuth hook to authenticate users via given credentials.

@see:

@see:

@example:

Very simple login process

const authenticator: Auth = new SomeAuth(); // implements Auth

export function signIn(
	serverUrl: string,
	username: string,
	password: string
): Promise<string> {
	return authenticator
		.signIn(serverUrl, username, password)
		.then(signInRes => {
			set({ user: signInRes.user, serverUrl });
			return signInRes.user;
		});
};

Properties

Methods

signIn (...)

function signIn (
   authServerUrl : string ,
   username : string ,
   password : string
) : Promise<SignInResult>

Tries to sign in to the server with the specified url using the given user credentials and resolves if the authentication was successful and otherwise rejects if the authentication was not successful.

@param:

authServerUrl - the url of the authentication server

@param:

username - the users name

@param:

password - the users password

@see:

@see:

@example:

Very simple login process

const authenticator: Auth = new SomeAuth(); // implements Auth

export function signIn(
	authServerUrl: string,
	username: string,
	password: string
): Promise<string> {
	return authenticator
		.signIn(authServerUrl, username, password)
		.then(signInRes => {
			set({ user: signInRes.user, authServerUrl });
			return signInRes.user;
		});
};
signOut (...)

function signOut ( ) : Promise<SignOutResult>

Tries to sign out from the server and close all connections.

@see:

@see:

@example:

A very simple logout process

const authenticator: Auth = new SomeAuth(); // implements Auth

export function signOut(): Promise<void> {
	return authenticator.signOut().then(res => {
		set({ user: null, serverUrl: null });
		if (res.reason) {
			logger.warn('User signed out because:', res.reason);
		}
	});
}
onAuthStateChanged (...)

function onAuthStateChanged (
   cb : (res: AuthResult) => void
) : () => void

Registers an event handler that gets called if an external auth state change happens.

@param:

cb - the handler that will be called

@see:

@see:

@see:

@example:

Registers on login and clean up on logout

const authenticator: Auth = new SomeAuth(); // implements Auth

// stores the cleanup for registered callback on authenticator
let cleanupCb: (() => void) | null = null;

export function signIn(
	serverUrl: string,
	username: string,
	password: string
): Promise<string> {
	// clean up callback
	if (cleanupCb) {
		cleanupCb();
		cleanupCb = null;
	}

	return authenticator
		.signIn(serverUrl, username, password)
		.then(signInRes => {
			cleanupCb = authenticator.onAuthStateChanged(changeRes => {
				if (changeRes.type === 'signOut' || changeRes.user !== get().user) {
					set({ user: null, serverUrl: null });
				}
			});
			set({ user: signInRes.user, serverUrl });
			return signInRes.user;
		});
};

export function signOut(): Promise<void> {
	// clean up callback
	if (cleanupCb) {
		cleanupCb();
		cleanupCb = null;
	}

	return authenticator.signOut().then(res => {
		set({ user: null, serverUrl: null });
	});
}

Position

type Position

Alias for: readonly [pageX: number, pageY: number]

A position description which specifies where the context menu should be rendered.

MenuItem

interface MenuItem

A definition for a menu item in a context menu. Each item should have a title and a corresponding action that is triggered if the user presses the context menu entry.

@see:

@see:

@example:

import Alert from '@spectrum-icons/workflow/Alert';

const items: MenuItem[] = [
	{
		title: 'First entry',
		action: () => alert('You clicked first entry')
	},
	{
		title: 'Second entry',
		icon: <Alert />,
		action: () => alert('You clicked second entry')
	}
];

Properties

title

Type: string

The title or label the menu entry should have.

icon ?

Type: ReactNode

An optional icon that are rendered within the menu entry beside the MenuItem.title. No icon gets displayed if the icon property is undefined.

action

Type: () => void

The action that is triggered if the users presses the menu entry.

Section

interface Section

A section contains multiple menu items and an optional title. Different sections in a context menu should be separated with a horizontal line for better visibility.

@see:

@see:

@example:

const section: Section = {
	title: 'Section',
	items: [
		{
			title: 'Entry 1',
			action: () => alert('Entry clicked')
		}
	]
};

const sections = [section, section2, section3];

Properties

title ?

Type: string

An optional title for the section that are rendered beside the section or the section separator.

items

Type: MenuItem[]

The menu items that are in this section.

@see:

PrefValue

type PrefValue

Alias for: JsonSerializable

the default type of a preference value

PrefRenderer

type PrefRenderer < T : PrefValue = PrefValue >

Alias for: (value: T, setValue: (newValue: T) => void) => ReactNode

Renders a React node that displays and changes the given preference in a proper way.

@typeParam:

T - the type of the preference (defaults to JsonSerializable)

@see:

Selector

type Selector

Alias for: string

the "name" of a group or preference

PrefSelector

type PrefSelector

Alias for: Selector

the type of a selector to select a preference out of a preference group

GroupSelector

type GroupSelector

Alias for: Selector | 'null'

the type of a selector to select a group out of a preference store

Preference

interface Preference < T : PrefValue = PrefValue >

a preference with a value and renderer

@typeParam:

T - the type of the preference (defaults to PrefValue)

@see:

@see:

@see:

Properties

value ?

Type: T

the current value of the preference

renderer ?

Type: PrefRenderer<T>

an update component which displays and changes the preference value in a proper way

PreferencesGroup

type PreferencesGroup

Alias for: Record<PrefSelector, Preference>

a group of preferences where every preference is accessible via a selector

PreferencesStore

type PreferencesStore

Alias for: Record<GroupSelector, PreferencesGroup>

the entire store of grouped preferences also accessible via a selector

The group null has a special meaning. It is the group for global preferences which do not have a group they belong to.

NotificationType

type NotificationType

Alias for: 'INFO' | 'SUCCESS' | 'WARNING' | 'ERROR'

The type of a notification. A notification of this type will show in the app in a specific way.

Notification

interface Notification

A generic notification that can be showed and stored. It has a [NotificationType | notification type](#NotificationType | notification type) and a dismissed flag to show the dismiss state.

Properties

type

Type: NotificationType

The type of the notification.

message

Type: string

The message of the notification. Usually it is a short abstract of the description and should not be multi-line.

description

Type: string

The description of the notification. Usually contains more detailed information and can be multi-line.

isDismissed

Type: boolean

Is true if the notification is dismissed.

AddressableMessage

interface AddressableMessage extends BaseMessage

a message that is addressable to a specific locations on the event bus

Properties

address

Type: ChannelAddress

the address of a event bus location registered to the backend

headers

Type: Headers

additional headers that will be sent with the message

replyAddress ?

Type: string

optional reply address to send a message back

very useful for a send-receive pattern where a backend node sends a message and waits for a receiving message

reply ?

Type: (message: any, callback: Callback, headers?: Headers) => void

Sends a message back to the sender with a actual content.

@param:

message - the content that will be sent with the message

@param:

callback - a callback function that will be invoked if the sender reply again.

@param:

headers - additional headers to send with the message

@example:

eb.registerHandler('awesome-channel', message => {
	if (message.replyAddress) {
		console.log(message.body); // ping
		message.reply('pong', () => {});
	}
});

BaseMessage

interface BaseMessage

a generic message that is sent to and received by the event bus

Properties

type

Type: 'ping' | 'register' | 'unregister' | 'publish' | 'send' | 'rec' | 'err'

every message must have a type so backend and frontend can differentiate between received and sent messages

Callback

type Callback < T : JsonSerializable = JsonSerializable >

Alias for: ( content: T ) => void

a function that is used as event handlers in the event bus when receiving messages

@see:

@see:

[EventBus.setupConnection | setupConnection (here socket.onmessage)](#EventBus.setupConnection | setupConnection (here socket.onmessage))

@example:

// some vertx channel
const channel = 'VERTX_CHANNEL';

const eventBus = new EventBus('http://localhost:8081/');

eventBus.onopen = () => {
	eventBus.registerHandler(channel, message => {
		console.log('Received message:', message);
	});
};

ContentMessage

interface ContentMessage extends AddressableMessage

a message with actual content that will be transferred with the message

Properties

body

Type: JsonSerializable

the content that will be transferred with the message

ErrorMessage

interface ErrorMessage extends BaseMessage

a message that is received from the event bus if something went wrong

Properties

type

Type: 'err'

No docs provided

failureCode

Type: number

the failure code of the received error

failureType

Type: string

additional error type of the received message

message

Type: string

additional information about the received error

Headers

interface Headers

headers that are sent with event bus messages

Properties

Message

type Message

Alias for: | PingMessage | RegisterMessage | UnregisterMessage | PublishMessage | SendMessage | ReceiveMessage | ErrorMessage

a message sent to and received from the event bus

PingMessage

interface PingMessage extends BaseMessage

a basic message that is sent to prove to the backend server that the client is still connected

Properties

type

Type: 'ping'

No docs provided

PublishMessage

interface PublishMessage extends ContentMessage

a message that gets broadcasted on a specified channel

Properties

type

Type: 'publish'

No docs provided

ReceiveMessage

interface ReceiveMessage extends ContentMessage

a message that is received from the event bus containing new information

Properties

type

Type: 'rec'

No docs provided

RegisterMessage

interface RegisterMessage extends AddressableMessage

a message that is sent to the backend server to register to a specific channel to receive future messages from the event bus from this specific channel

to unregister or unsubscribe from the channel, use UnregisterMessage

Properties

type

Type: 'register'

No docs provided

SendMessage

interface SendMessage extends ContentMessage

a message that is sent on the specified channel containing a reply address gets sent

Properties

type

Type: 'send'

No docs provided

UnregisterMessage

interface UnregisterMessage extends AddressableMessage

a message that is sent to the backend server to unregister or unsubscribe from a specific channel to not receive any further messages from this channel

to register to a channel, use RegisterMessage

Properties

type

Type: 'unregister'

No docs provided

Options

interface Options

the default options for the event bus

Properties

autoReconnect

Type: boolean

When true, the event bus tries to reconnect automatically if the connection with the backend is lost.

Defaults to true.

pingInterval

Type: number

Time between ping messages sent to the backend server in milliseconds.

Defaults to 5000 ms.

reconnectAttempts

Type: number

Number of attempts to try to reconnect to the backend server before no more reconnects get attempted.

Defaults to Infinity.

reconnectExponent

Type: number

Exponent of the power function used to determine a new reconnect delay based on reconnect attempts.

For implementation details, see @wuespace/vertx-event-bus#EventBus.newReconnectDelay.

Defaults to 2.

delayMin

Type: number

Minimum time to wait between reconnect attempts in milliseconds.

Defaults to 1000 ms.

delayMax

Type: number

Maximum time to wait between reconnect attempts in milliseconds.

Defaults to 5000 ms.

randomizationFactor

Type: number

Randomization factor for the deviation used in the reconnect delay generator function.

For implementation details, see @wuespace/vertx-event-bus#EventBus.newReconnectDelay.

Defaults to 0.5.

logger ?

Type: ComponentLogger

Optional component logger where the event bus logs internal information and debug messages.

Defaults to undefined.

ChannelAddress

type ChannelAddress

Alias for: string

The type of a communication channel address in the event bus.

StaticSpectrumColor

type StaticSpectrumColor

Alias for: | 'static-black' | 'static-white' | `static-${'gray'}-${R50900}` | `static-${'red' | 'orange' | 'green' | 'fuchsia'}-${R400700}` | `static-${'chartreuse'}-${R300700}` | `static-${'purple'}-${R400800}` | `static-${ | 'celery' | 'yellow' | 'magenta' | 'indigo' | 'seafoam'}-${R200700}` | `static-${'blue'}-${R200800}`

A static spectrum color definition which is persistent across all themes.

SpectrumColor

type SpectrumColor

Alias for: | StaticSpectrumColor | `${ | 'celery' | 'chartreuse' | 'yellow' | 'magenta' | 'fuchsia' | 'purple' | 'indigo' | 'seafoam' | 'red' | 'orange' | 'green' | 'blue'}-${R400700}` | `${'gray'}-${R50900}`

A spectrum color definition which adapts to the current spectrum theme.