GitHub Homepage React Spectrum Libraries Legal Notice

@wuespace/telestion-client-common

Install using

npm install @wuespace/telestion-client-common

Exported Members

You can access these members by importing the module:

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

ContextMenu

function ContextMenu (
   { sections, style, isOpen, onClose } : ContextMenuProps
) : any

Renders a context menu at the given position with the specified menu entries.

@see:

@example:

ContextMenuProviderProps['menu'] = (
	sections,
	style,
	isOpen,
	close
) => (
	<ContentMenu
		sections={sections}
		style={style}
		isOpen={isOpen}
		onClose={close}
	/>
);

function App() {
	return (
		<ContextMenuProvider menu={menu}>
			{...componentsContainingWrappers}
		</ContextMenuProvider>
	);
}

ContextMenuProps

interface ContextMenuProps

React Props of ContextMenu

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

sections

Type: Section[]

The sections that the menu component should display.

style

Type: CSSProperties

The style of the menu container. (contains the absolute styling)

isOpen

Type: boolean

When true the menu should is displayed.

onClose

Type: () => void

A function that are called when the menu should close.

ContextMenuProvider

function ContextMenuProvider (
   { children, menu } : ContextMenuProviderProps
) : any

The provider is the container element for the application context menu. It provides the context and states to subsequent context menu wrappers lower in the tree and handles the context menu logic.

It is by default provided via the CommonWrapper element. If you prefer to setup your application manually, please wrap your components in this provider function to enable access to the context menu via the ContextMenuWrapper.

This component requires a menu that should render the context menu.

@see:

@see:

@see:

@example:

ContextMenuProviderProps['menu'] = (
	sections,
	style,
	isOpen,
	close
) => <Menu sections={sections} style={style} isOpen={isOpen} onClose={close} />;

function App() {
	return (
		<ContextMenuProvider menu={menu}>
			{...componentsContainingWrappers}
		</ContextMenuProvider>
	);
}

ContextMenuProviderProps

interface ContextMenuProviderProps

React Props of ContextMenuProvider

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

menu

Type: ( sections: Section[], style: CSSProperties, isOpen: boolean, close: () => void ) => ReactNode

A function that provides state and style to a component which renders the menu structure and handles the user inputs.

@param:

sections - the sections that the menu component should display

@param:

style - the style of the menu container (contains the absolute styling)

@param:

isOpen - is true when the menu should be displayed

@param:

close - a function to call when the menu should close

children

Type: ReactNode

The children components which have access to the context menu context via the ContextMenuWrapper component.

ContextMenuWrapper

function ContextMenuWrapper (
   { menuItems, disableCascade = false, title, children } : ContextMenuWrapperProps
) : any

The wrapper provides access to the context menu and allows the injection or replacement of menu items deeply nested in the component tree.

These menu items are displayed in the context menu only for this component and their children beside menu items that are registered higher up in the tree.

This component is intended to be used nested inside each other.

Set the disableCascade property to true to "overwrite" the currently registered menu items higher up in the tree.

The ContextMenuProvider is required higher up in the tree for this component to work.

@see:

@see:

@example:

const items: MenuItem[] = [
	{
		title: 'Element1 1',
		action: () => alert('Element1 1')
	},
	{
		title: 'Element1 2',
		action: () => alert('Element1 2')
	}
];

function MyComponent({ children }: Props) {
	return (
		<ContextMenuWrapper menuItems={items}>
			{children}
		</ContextMenuWrapper>
	);
}

ContextMenuWrapperProps

interface ContextMenuWrapperProps

React Props of ContextMenuWrapper

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

menuItems

Type: MenuItem[]

The menu items that should be accessible via the context menu on this component.

title ?

Type: string

An optional title of the section in the context menu.

disableCascade ?

Type: boolean

Disables the rendering of sections in the context menu that are registered higher up in the tree.

children

Type: ReactNode

The components that should have the registered ContextMenuWrapperProps.menuItems in their context menu.

function useLogo ( ) : string

Returns the path to the current application logo. It can be replaced by a custom logo in the CommonWrapper component.

@throws:

TypeError - if called outside of the CommonWrapper

@see:

@see:

@example:

function AppLogo() {
	const appLogo = useLogo();
	return <Image src={appLogo} alt="Application logo" />;
}

useWidgets

function useWidgets ( ) : Array<Widget>

Returns a list of all registered widgets in the application.

@throws:

TypeError - if called outside of the CommonWrapper

@see:

@see:

@example:

function RegisteredWidgets() {
	const widgets = useWidgets();
	const names = widgets.map(widget => widget.name);

	return (
		<ul>
			{names.map(name => <li>{name}</li>)}
		</ul>
	);
}

AccountControls

function AccountControls ( ) : any

Part of the Telestion Client Common header.

This header component lets the user review and control their login and authentication status.

It displays the current login status as well as some further information about the event bus state.

It renders a simple avatar icon with a dropdown menu attached to it.

@see:

@example:

function AppHeader() {
	return (
		<Header
			right={
				<AccountControls />
			}
		/>
	);
}

Actions

function Actions (
   { children } : ActionsProps
) : any

Part of the Telestion Client Common header.

It displays customizable actions which gives the user direct access to the application settings.

Predefined and ready-to-use actions are:

@see:

@see:

@see:

@see:

@see:

@see:

@example:

function AppHeader() {
	return (
		<Header
			right={
				<Actions>
					<ColorSchemeAction />
					<NotificationAction />
				</Actions>
			}
		/>
	);
}

ActionsProps

interface ActionsProps

React Props of Actions

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

children

Type: ReactElement | ReactElement[]

Components or "actions" the header action component should render.

Typical pre-defined actions are:

ActionDivider

function ActionDivider ( ) : any

Part of the header actions.

This is a special action where the actions around this action are divided via a vertical bar.

The action is useful grouping registered actions into subgroups for a better overview.

This is also specified in the Adobe Spectrum Design: https://spectrum.adobe.com/page/headers/#Collapsing-Action-Buttons

@see:

@see:

@example:

function MyActions() {
	return (
		<Actions>
			<NotificationAction />
			<ActionDivider />
			<ColorSchemeAction />
		</Actions>
	);
}

ColorSchemeAction

function ColorSchemeAction ( ) : any

Part of the header actions.

This action lets the user control the current color scheme of the application.

Three states are possible:

  • 'system'
  • 'light'
  • 'dark'

On every click, the color scheme switches to the next state: system -> light -> dark -> system -> ...

@see:

@see:

@example:

function MyActions() {
	return (
		<Actions>
			<ColorSchemeAction />
		</Actions>
	);
}

NotificationAction

function NotificationAction ( ) : any

Part of the header actions.

This action lets the user control the current notification state of the application.

The user can switch between normal notification and silent mode. In silent mode, no more notifications are displayed. For more information take a look on the @wuespace/telestion-client-core#useNotifications hook.

@see:

@see:

@example:

function MyActions() {
	return (
		<Actions>
			<NotificationAction />
		</Actions>
	);
}

FullscreenAction

function FullscreenAction ( ) : any

Part of the header actions.

This action lets the user control whether the application gets shown in fullscreen.

The user can switch between default window mode and fullscreen mode where the application or browser content is rendered over the entire screen.

@see:

@example:

function MyActions() {
	return (
		<Actions>
			<FullscreenAction />
		</Actions>
	);
}

DashboardPicker

function DashboardPicker ( ) : any

Part of the Telestion Client Common header.

It displays a picker element which lists all available dashboards the current user have.

If the user has no dashboard defined yet, it renders a placeholder message. It detects path changes and triggers path changes to the necessary dashboard page.

If nobody is logged in, it hides itself a valid authentication arrives.

@see:

@see:

@example:

function AppHeader() {
	return (
		<Header
			middle={<DashboardPicker />}
		/>
	);
}

NavBar

function NavBar (
   { links } : NavBarProps
) : any

Part of the Telestion Client Common header.

It displays the given links in a React Spectrum tab list. If no links are set the application title are shown instead.

@see:

@see:

@see:

@example:

Display only title:

function AppHeader() {
	return (
		<Header
			left={<NavBar />}
		/>
	);
}

Display some links:

const links: Array<Link> = [
	{
		title: 'Dashboards',
		path: '/dashboard'
	},
	{
		title: 'Preferences',
		path: '/preferences'
	}
];

function AppHeader() {
	return (
		<Header
			left={<NavBar links={links} />}
		/>
	);
}

NavBarProps

interface NavBarProps

React Props of NavBar

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

links ?

Type: Array<Link>

Links to display in a tab list. If no links are set the application are shown.

@see:

function AppLogo ( ) : any

Part of the Telestion Client Common header.

It displays the current application logo fit inside the header component. If no logo is specified in the CommonWrapper the default Telestion Logo is used.

@see:

@see:

@example:

function AppHeader() {
	return (
		<Header
			left={<AppLogo />}
		/>
	);
}

ConnectionIndicator

function ConnectionIndicator (
   { overrideState } : { overrideState?: 'connected' | 'disconnected' | 'error' | 'noEventBus'; }
) : any

Part of the Telestion Client Common header.

It displays the current connection status of the event bus with a status light.

@see:

@see:

@see:

@example:

function AppHeader() {
	return (
		<Header
			right={<ConnectionIndicator />}
		/>
	);
}

Header

function Header (
   { left, center, right } : HeaderProps
) : any

The Header component of Telestion Client Common.

It displays a header in style of the Adobe Spectrum header pattern. Components of the header can be left, center or right aligned.

@see:

@see:

@see:

@see:

@see:

@see:

@see:

@see:

@see:

@example:

function AppHeader() {
	return (
		<Header
			left={
				<>
					<AppLogo />
					<NavBar />
				</>
			}
			center={<DashboardPicker>}
			right={
				<>
					<ConnectionIndicator />
					<Actions>
					  <ColorSchemeAction />
					</Actions>
					<AccountControls />
				</>
			}
		/>
	);
}

HeaderProps

interface HeaderProps

React Props of Header

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

left ?

Type: ReactElement | ReactElement[]

Header components aligned on the left side of the header.

center ?

Type: ReactElement | ReactElement[]

Header components aligned in the center of the header.

right ?

Type: ReactElement | ReactElement[]

Header components aligned on the right side of the header.

DashboardPage

function DashboardPage ( ) : any

A Telestion Client page that renders a dashboard page. It displays the currently active dashboard of an authenticated user.

It can be changed with the DashboardPicker component usually used in the application header. To register a new dashboard for the user or change existing, use the useUserConfig hook.

It only renders if someone is authenticated. Otherwise, it redirects to the login page.

Attention

If you create your own dashboard page, please pass the routing information so that the pages component read it and render the page the right way: MyDashboardPage.routing = TCDashboardPage.routing;

@see:

@see:

@see:

@see:

@example:

function App() {
	return (
		<TelestionClient>
			<Pages>
				<LoginPage />
				<DashboardPage />
				<NotFoundPage />
			</Pages>
		</TelestionClient>
	);
}

LoginForm

function LoginForm (
   { initialServerURL, initialUsername } : LoginFormProps
) : any

The form component that renders the react-spectrum login form where the user enters their information and credentials to log in with.

This component belongs to the LoginPage

@see:

@see:

@see:

@example:

function MyLoginPage() {
	return (
		<LoginPage>
			<LoginLogo />
			<LoginTitle />
			<LoginDescription />
			<LoginForm initialServerURL="http://localhost:9870/bridge" />
		</LoginPage>
	);
}

MyLoginPage.routing = TCLoginPage.routing;

LoginFormProps

interface LoginFormProps

React Props of LoginForm

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

initialServerURL ?

Type: string

The initial value of the server url text field in the LoginForm component.

initialUsername ?

Type: string

The initial value of the username text field in the LoginForm component.

LoginDescription

function LoginDescription (
   { description, children } : LoginDescriptionProps
) : any

The login description component that renders the current login description in the login page.

It defaults to:

Please enter the credentials assigned to you by the Ground Station team

and can be overridden by the prop LoginDescriptionProps.description or can be completely replaced by another component via defined children.

Attention

If children are specified, the overridden description is completely ignored and the children are rendered instead!

This component belongs to the LoginPage

@see:

@see:

@example:

function MyLoginPage() {
	return (
		<LoginPage>
			<LoginLogo />
			<LoginTitle />
			<LoginDescription />
			<LoginForm initialServerURL="http://localhost:9870/bridge" />
		</LoginPage>
	);
}

MyLoginPage.routing = TCLoginPage.routing;

LoginDescriptionProps

interface LoginDescriptionProps

React Props of LoginDescription

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

description ?

Type: string

The alternative description to use instead of the default one.

children ?

Type: ReactElement | Array<ReactElement>

Components that completely replace the description and are rendered instead.

function LoginLogo ( ) : any

The login logo component that renders the current application logo in the login page.

This component belongs to the LoginPage

@see:

@example:

function MyLoginPage() {
	return (
		<LoginPage>
			<LoginLogo />
			<LoginTitle />
			<LoginDescription />
			<LoginForm initialServerURL="http://localhost:9870/bridge" />
		</LoginPage>
	);
}

MyLoginPage.routing = TCLoginPage.routing;

LoginPage

function LoginPage (
   { children } : LoginPageProps
) : any

A Telestion Client page that renders a login page where the user typically enters their credentials to log into the application.

It only renders if nobody is authenticated. Otherwise, it redirects to the dashboard page.

It aligns its children vertically.

Possible children components are:

  • Attention

If you create your own login page, please pass the routing information so that the pages component read it and render the page the right way: MyLoginPage.routing = TCLoginPage.routing;

@see:

{@Link LoginPageProps}

@see:

@see:

@see:

@see:

@see:

@example:

function MyLoginPage() {
	return (
		<LoginPage>
			<LoginLogo />
			<LoginTitle />
			<LoginDescription />
			<LoginForm initialServerURL="http://localhost:9870/bridge" />
		</LoginPage>
	);
}

MyLoginPage.routing = TCLoginPage.routing;

LoginPageProps

interface LoginPageProps

React Props of LoginPageProps

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

children

Type: ReactElement | Array<ReactElement>

Components that the login page should render.

Typical pre-defined components are:

LoginTitle

function LoginTitle ( ) : any

The login title component that renders the current application title in the login page.

This component belongs to the LoginPage

@see:

@example:

function MyLoginPage() {
	return (
		<LoginPage>
			<LoginLogo />
			<LoginTitle />
			<LoginDescription />
			<LoginForm initialServerURL="http://localhost:9870/bridge" />
		</LoginPage>
	);
}

MyLoginPage.routing = TCLoginPage.routing;

NotFoundPage

function NotFoundPage ( ) : any

A Telestion Client page that renders a fallback page if the current route doesn't fit a page higher up in the list. The component displays a "not found" message and a button to return to the dashboard page if the user is logged in. Otherwise, the component redirects to the login page.

It renders regardless if the user is authenticated or not.

Attention

If you create your own not found page, please pass the routing information so that the pages component read it and render the page the right way: MyNotFoundPage.routing = TCNotFoundPage.routing;

@see:

@example:

function App() {
	return (
		<TelestionClient>
			<Pages>
				<LoginPage />
				<DashboardPage />
				<NotFoundPage />
			</Pages>
		</TelestionClient>
	);
}

LoadingIndicator

function LoadingIndicator < T : readonly any[] > (
   { children, dependencies, timeout = 0 } : LoadingIndicatorProps<T>
) : any

Renders a loading indicator if some of the dependencies are not defined.

@typeParam:

T - the tuple which represents the dependencies to check

@throws:

Error - if some dependencies are undefined until timeout and timeout is set

@see:

@example:

Renders a loading indicator if position is undefined otherwise the child which displays the current position.

const [position, setPosition] = useState<Position>();
const [height, setHeight] = useState<number>();

return (
	<LoadingIndicator dependencies={[position, height]}>
		{(currentPos, currentHeight) => (
			<p>{currentPos} - {currentHeight}</p>
		)}
	</LoadingIndicator>
);

LoadingIndicatorProps

interface LoadingIndicatorProps < T : readonly any[] >

React Props of LoadingIndicator

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

@typeParam:

T - the tuple which represents the dependencies to check

@see:

@see:

Properties

children

Type: (...dependencies: [...T]) => JSX.Element | string | number | null

A function to children to display them if all dependencies are defined. The defined dependencies are given as argument to the function for later use.

@example:

<LoadingIndicator dependencies={['defined']}>
	{([value]) => <p>Current value: {value}</p>}
</LoadingIndicator>
dependencies

Type: [...Undefinable<T>]

The dependencies to check if some of them are undefined.

timeout ?

Type: number

The timeout in milliseconds until the function throws, if it is 0 it waits indefinitely.

OverflowFix

function OverflowFix (
   { children, ...viewProps } : OverflowFixProps
) : any

Prevents the children of this component from overflowing and breaking the application's layout. The children of this component are wrapped inside a container with a defined size. If the children needs more space than the parent container has, it overflows and the parent container renders vertical and horizontal scrollbars if necessary. The user can now scroll through the bigger children via the scrollbars and no component inside the overflow fix breaks the outside layout.

In the background, it uses the @adobe/react-spectrum#View component. All props of this component get passed to the outer @adobe/react-spectrum#View container.

@see:

@see:

@example:

function MyComponent() {
	return (
	  <OverflowFix borderRadius="regular">
	  	<IWillDefinitelyOverflow />
	  </OverflowFix>
	); // not anymore :D
}

OverflowFixProps

interface OverflowFixProps extends ViewProps

React Props of OverflowFix

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

children

Type: ReactNode

The components which are possibly overflowing.

CommonWrapper

function CommonWrapper (
   { appLogo, widgets, children } : CommonWrapperProps
) : any

The wrapper component of the Telestion Client Common library.

It defines the basic display structure in form of a vertical flex element.

@see:

@example:

const widgets: Array<Widget> = [
	...commonWidgets,
	...projectWidgets
];

function App() {
	return (
		<TelestionClient
			wrapper={children => (
			  <CommonWrapper widgets={widgets}>
			  	{children}
			 	</CommonWrapper>
			)}
		>
			<Pages>
				...
			</Pages>
		</TelestionClient>
	);
}

CommonWrapperProps

interface CommonWrapperProps

React Props of CommonWrapper

For more information about React Props, please look here: https://reactjs.org/docs/components-and-props.html

Properties

Type: string

Path to a custom application logo that are used instead of the default Telestion logo.

widgets ?

Type: Array<Widget>

Registered widgets for the application to use.

children

Type: ReactElement | ReactElement[]

The children received from the wrapper function of the "root" component @wuespace/telestion-client-core#TelestionClient.

useCurrentDashboards

function useCurrentDashboards ( ) : [ Array<Dashboard> | undefined, DispatchDashboards ]

Gets and sets the current dashboards for the current authenticated user.

If no user is authenticated the returned dashboards are undefined.

The update function is stable as long as the authenticated user does not change.

Usage and behaviour inspired from the React useState hook.

@returns:

a tuple of the current dashboards and a setter function to update the dashboards for the current user.

@see:

@see:

@see:

@example:

Get and set dashboards for an authenticated user

function MyComponent() {
	const [dashboards, setDashboards] = useCurrentDashboards();

 return (
 	<div>
 		<RenderDashboards dashboards={dashboards} />
 		<button onClick={() => setDashboards([])}>
 			Clear dashboards
 		</button>
 	</div>
 );
}

useDarkColorScheme

function useDarkColorScheme ( ) : boolean

Returns true if the application is currently in dark mode.

@see:

@throws:

TypeError - if invalid color scheme state from useColorScheme received

@example:

function MyComponent() {
	const isDark = useDarkColorScheme();
 return (
   <div style={isDark ? { color: 'white' } : { color: 'black }}>
     Hello World
   </div>
 );
}

useDashboards

function useDashboards (
   username : Username
) : [Array<Dashboard> | undefined, DispatchDashboards]

Gets and sets the current dashboards for a specific user.

If the user does not exist in the user config store the returned dashboards are undefined.

The update function is stable as long as the username not changes.

Usage and behaviour inspired from the React useState hook.

@param:

username - the username of the dashboards to obtain

@returns:

a tuple of the current dashboards and a setter function to update the dashboards for the current user.

@see:

@see:

@see:

@example:

Get and set dashboards for specific user

function MyComponent() {
	const [dashboards, setDashboards] = useDashboards('Alice');

 return (
 	<div>
 		<RenderDashboards dashboards={dashboards} />
 		<button onClick={() => setDashboards([])}>
 			Clear dashboards
 		</button>
 	</div>
 );
}

DispatchDashboards

type DispatchDashboards

Alias for: Dispatch<SetStateAction<Array<Dashboard>>>

A dispatch function type to change dashboards in a React useState style.

useColorScheme

const : UseStore<ColorSchemeState>

Returns the color scheme state and actions to interact with. A selector can be defined to pick out parts of the store. If correctly set up, the function only triggers a rerender if the selected values have changed.

For more information about state management in Zustand, take a look at their [https://github.com/pmndrs/zustand | GitHub page](#https://github.com/pmndrs/zustand | GitHub page).

@param:

selector - optional selector function which picks the specified elements out of the store

@param:

equalityFn - optional equality function to check for state updates on the picked elements

@returns:

the picked elements in the selector function

@see:

@see:

@see:

@see:

@example:

Get and set color scheme:

function ColorSchemeChanger() {
	const { colorScheme, set } = useColorScheme(
		state => ({
			colorScheme: state.colorScheme,
			set: state.set
		}),
		shallow
	);

	return (
		<>
		  <p>Current colorscheme: {colorScheme}</p>
		  <button onClick={() => set('dark')}>Set dark</button>;
		</>
	);
}

showDialog

function showDialog < T = undefined > (
   id : string ,
   config : DialogConfig<T>
) : Promise<T>

Shows a new dialog configured with the specified options.

@param:

id - the id of the modal, should be unique inside the project

@param:

config - the specified options to customize the dialog

@returns:

a Promise which resolves, when the user confirmed and rejects, when the user canceled the dialog

@typeParam:

T - The type of state to provide to the different components

@example:

import { showDialog } from '@wuespace/telestion-client-common';

function MyComponent() {
	const openDialog = () => {
		showDialog('my-dialog', { title: 'My Dialog', content: 'Hello World' })
			.then(() => alert("Confirmed"))
			.catch(() => alert("Canceled"));
	};

	return <button onClick={openDialog}>Show Dialog</button>;
}

useDialog

const : UseStore<DialogState>

Returns the dialog state and action to interact with. A selector can be defined to pick out parts of the store. If correctly set up, the function only triggers a rerender if the selected values have changed.

For more information about state management in Zustand, take a look at their [https://github.com/pmndrs/zustand | GitHub page](#https://github.com/pmndrs/zustand | GitHub page).

@param:

selector - optional selector function which picks the specified elements out of the store

@param:

equalityFn - optional equality function to check for state updates on the picked elements

@returns:

the picked elements in the selector function

@see:

@see:

@see:

@see:

@example:

import { StateSelector } from 'zustand';
import {
	useDialog,
	DialogState
} from '@wuespace/telestion-client-common';

// selector does not depend on scope, so it's better to define it outside
// to not re-declare it on every render
const selector: StateSelector<DialogState, DialogState['show']> =
	state => state.show;

function MyComponent() {
	const show = useUserConfig(selector);

	const openDialog = () => {
		show('my-dialog', { title: 'My Dialog', content: 'Hello World' })
			.then(() => alert("Confirmed"))
			.catch(() => alert("Canceled"));
	};

	return <button onClick={openDialog}>Show Dialog</button>;
}

useUserConfig

const : UseStore<UserConfigState>

Returns the user config state and actions to interact with. A selector can be defined to pick out parts of the store. If correctly set up, the function only triggers a rerender if the selected values have changed.

For more information about state management in Zustand, take a look at their [https://github.com/pmndrs/zustand | GitHub page](#https://github.com/pmndrs/zustand | GitHub page).

@param:

selector - optional selector function which picks the specified elements out of the store

@param:

equalityFn - optional equality function to check for state updates on the picked elements

@returns:

the picked elements in the selector function

@see:

@see:

@see:

@see:

@example:

Fetch available usernames from the store:

function Notifications() {
	const usernames = useUserConfig(state => Object.keys(state.userConfig));

	return (
		<ul>
			{notifications.map(notification => (
				<li>{notification}</li>
			)}
		</ul>
	);
}

Performance optimized and type-safe fetching from the store:

import { useCallback, ReactNode } from 'react';
import { StateSelector } from 'zustand';
import shallow from 'zustand/shallow';
import {
	useUserConfig,
	UserConfigState
} from '@wuespace/telestion-client-common';

// selector does not depend on scope, so it's better to define it outside
// to not re-declare it on every render
const selector: StateSelector<
	UserConfigState,
	{
		add: UserConfigState['addUser'],
		remove: UserConfigState['removeUser']
	}
> = state => ({
	add: state.addUser,
	remove: state.removeUser
});

function MyComponent() {
	const { add, remove } = useUserConfig(selector, shallow);

	return (
		<div>
			<button onClick={() => add('Alice', { dashboards: [] })}>
				Add user 'Alice' to the user configurations
			</button>
			<button onClick={() => remove('Alice')}>
				Remove user 'Alice' from the user configurations
			</button>
		</div>
	);
}

ColorScheme

type ColorScheme

Alias for: 'light' | 'dark' | 'system'

Type of a valid color scheme:

  • light - use always the light theme
  • dark - use always the dark theme
  • system - use the system defined colorscheme

ColorSchemeState

interface ColorSchemeState extends State

The color scheme store and actions of Telestion Client Common.

Stores and handles the current color scheme of the application.

Properties

colorScheme

Type: ColorScheme

The current color scheme of the application.

@see:

set

Type: (colorScheme: ColorScheme) => void

Sets a new color scheme for the application.

@param:

colorScheme - the new color scheme to use

@see:

CallableComponent

type CallableComponent < T >

Alias for: ( state: T, setState: (partial: Partial<T>) => void ) => ReactNode

A function that provides the current state and a function to change it. It returns a valid react node.

@param:

state - the current state

@param:

setState - a function to partially update the state

@returns:

a valid react node

@typeParam:

T - The type of state to provide to the different components

DialogConfig

interface DialogConfig < T >

A configuration object to customize a dialog created via the DialogState.show function.

@typeParam:

T - The type of state to provide to the different components

Properties

title

Type: ReactNode | CallableComponent<T>

The title of the dialog displayed in the upper left corner.

header ?

Type: string | ReactNode | CallableComponent<T>

An optional header of the dialog displayed in the upper right corner.

content

Type: string | ReactNode | CallableComponent<T>

The content of the dialog rendered below the title and header in the center of the dialog.

footer ?

Type: ReactNode | CallableComponent<T>

An optional footer of the dialog in the lower left corner.

initialState

Type: T

The initial value

Dialog

interface Dialog < T >

A dialog which is registered in the Telestion Common dialog state.

Every dialog has an id which is unique inside the project.

@typeParam:

T - The type of state to provide to the different components

Properties

id

Type: string

The unique id of the dialog given via the DialogState.show function.

config

Type: DialogConfig<T>

The configuration of the dialog given via the DialogState.show function.

isOpen

Type: boolean

When true, the dialog is currently open.

onConfirm

Type: (final: T) => void

A handler to confirm the opened dialog.

@param:

final - the final state which the resolved promise return

onCancel

Type: () => void

A handler to cancel the opened dialog.

DialogState

interface DialogState extends State

The dialog store and actions of Telestion Client Common.

Stores and handles show dialog calls from projects and common itself.

Properties

dialogs

Type: Array<Dialog<any>>

Stores the currently registered dialogs.

@see:

Methods

show (...)

function show < T = undefined > (
   id : string ,
   config : DialogConfig<T>
) : Promise<T>

Registers and opens a new dialog configured with the specified options.

@param:

id - the id of the modal, should be unique inside the project

@param:

config - the specified options to customize the dialog

@returns:

a Promise which resolves with the current state, when the user confirms and rejects, when the user canceled the dialog

@typeParam:

T - The type of state to provide to the different components

UserConfigState

interface UserConfigState extends State

The user configs store and actions of Telestion Client Common.

Stores and handles user configurations.

Properties

userConfig

Type: UserConfig

The current user config for the application. It stores the user information associated to the username.

@see:

@example:

Get user information for one user

const infos = useUserConfig(state => state.userConfig['Alice']);

console.log(infos.dashboards);
addUser

Type: (username: Username, information: UserInformation) => void

Adds a user to the user config store.

@param:

username - the username of the user

@param:

information - some additional information linked to the username

@throws:

TypeError - if the username is not valid

@throws:

TypeError - if the username already exists in the store

@see:

@see:

removeUser

Type: (username: Username) => void

Deletes a user from the user config store.

@param:

username - the username of the information to delete

@throws:

TypeError - if the username does not exists in the store

updateUserInfo

Type: ( username: Username, newState: SetPartialStateAction<UserInformation> ) => void

Updates the user information for a username.

@param:

username - the username of the information to update

@param:

newState - the new information for the username

@throws:

TypeError - if the username does not exists in the store

set

Type: (userConfig: UserConfig) => void

Replaces the current user config store with the given one.

@param:

userConfig - the new user config store

@see:

clear

Type: () => void

Clears the entire user config store and deletes every user configuration.

useBooleanState

function useBooleanState (
   initialState : InitialState = false
) : ReturnType

Creates a React state which only can switch between true and false. It returns the current boolean value and two functions to update the current state which are stable between re-renders.

This hook is useful in situations where you open or close a modal or switch between two different modes in your component.

@param:

initialState - the initial value of the boolean state (same as useState's initial state)

@example:

function MyComponent() {
	const [state, open, close] = useBooleanState();

	return (
		<div>
			<div>
				<button onClick={open}>Open Modal</button>
				<button onClick={close}>Close Modal</button>
			</div>
			<Modal state={state}>
				{...content}
			</Modal>
		</div>
	);
}

InitialState

type InitialState

Alias for: boolean | (() => boolean)

The type for the initial state of the useBooleanState hook. (same as useState's initial state)

ReturnType

type ReturnType

Alias for: readonly [ /** * The current boolean state. */ state: boolean, /** * A function to set the boolean state to `true`. * (this function is stable) */ setTrue: () => void, /** * A function to set the boolean state to `false`. * (this function is stable) */ setFalse: () => void ]

The return type of the useBooleanState hook.

useEvent

function useEvent < O : HTMLElement , K : keyof HTMLElementEventMap > (
   type : K ,
   onContext : (event: HTMLElementEventMap[K]) => void
) : RefObject<O>

Registers an event handler to a HTML element. The returned ref should be attached to the HTML element that should trigger the registered event.

@param:

type - the type of event that should trigger the onContext function

@param:

onContext - the function that should be called on a event on the HTML element

@example:

const handle = () => alert('Context alert');

function MyComponent({ children }: Props) {
	const ref = useEvent('contextmenu', handle);

	return (
		<div ref={ref}>
			{children}
		</div>
	);
}

useStoredState

function useStoredState < T : JsonSerializable > (
   key : string ,
   defaultState : T
) : [T, Dispatch<SetStateAction<T>>]

Use a state which gets saved in the localStorage

@param:

key - the key for storing it in the localStorage

@param:

defaultState - the default value if no value was previously set

@example:

function MyComponent() {
	const [myState, setMyState] = useState('my-key', 'hello world');

	return (
		<div>
			<div>{myState}</div>
			<button onClick={() => setMyState('Clicked')}>Change State</button>
			<button onClick={() => location.reload()}>Reload Page</button>
		</div>
	);
}

useDependencyTimeout

function useDependencyTimeout < T : readonly any[] > (
   timeout : undefined = 0 ,
   dependencies : [...Undefinable<T>]
) : dependencies is [...T]

Throws an error after a timeout if any dependency is undefined.

@param:

dependencies - the dependencies to check if they are undefined

@param:

timeout - the timeout in milliseconds until the function throws, if it is 0 it waits indefinitely

@returns:

the current state of undefined dependencies

@typeParam:

T - the tuple which represents the dependencies to check

@throws:

Error - if some dependencies are undefined until timeout and timeout is set

@example:

const [position, setPosition] = useState<Position>();

// throws if no position received after 5 seconds
if (useDependencyTimeout(5000, [position])) {
	// type guarded - "position" is always defined
	return <p>Latest position: {position}</p>;
}

return <p>Waiting for incoming data</p>;

useSpectrumColor

function useSpectrumColor (
   spectrumColors : SpectrumColor[]
) : string[]

Converts the given spectrum colors to hexadecimal colors. It respects the application color scheme and changes to the suitable color.

@param:

spectrumColors - the spectrum colors to convert to hexadecimal values

@returns:

the hexadecimal values

@example:

const [color1, color2] = useSpectrumColor(['indigo-400', 'yellow-700']);

console.log(color1); // #7575f1
console.log(color2); // c4a600

Optional

type Optional < T , K : keyof T >

Alias for: Omit<T, K> & Partial<Pick<T, K>>

Makes the keys K from the interface S optional.

@typeParam:

T - the interface the keys K to make some optional

@typeParam:

K - the union of keys from S to make optional

@see:

@example:

interface Foo {
	foo: string;
	bar: boolean;
	baz: number;
}

type FooWithOptional = Optional<Foo, 'foo' | 'bar'>;

SetPartialStateAction

type SetPartialStateAction < S >

Alias for: | Partial<S> | ((prevState: S) => Partial<S>)

A state update for state type S with new parts of a state or a function that receives the current state and expects parts of a new state.

Following the React SetStateAction principle.

@typeParam:

S - the full state type

@see:

Undefinable

type Undefinable < T : readonly any[] >

Alias for: { [P in keyof T]: T[P] | undefined; }

Makes all elements in a tuple undefinable. It adds the type undefined to possible type of every tuple element.

@typeParam:

T - the tuple to extend its elements with undefined

See https://github.com/microsoft/TypeScript/pull/26063 for more information.

StaticColorMap

type StaticColorMap

Alias for: Record<StaticSpectrumColor, string>

A type which maps a static spectrum color to a color value.

ColorMap

type ColorMap

Alias for: Record<SpectrumColor, string>

A type which maps a spectrum color to a color value for a specific spectrum color theme.

staticColors

const : StaticColorMap

Spectrum Static Colors which are persistent across all themes.

lightColors

const : ColorMap

Spectrum Colors for the "light" spectrum theme.

darkColors

const : ColorMap

Spectrum Colors for the "dark" spectrum theme.

isDefinedValue

function isDefinedValue < T > (
   value : T | undefined
) : value is T

A type guard to check if the given value is undefined.

@param:

value - the value to check if it is undefined

@typeParam:

T - the defined type of the value

@example:

const myList = ['Foo', 42, undefined, 'bar'];

myList.every(isDefinedValue); // false

commonWidgets

const : Widget[]

No docs provided

eventbusDebugWidget

const : Widget

A widget that show's debug information about the eventbus connection. It's accessible via the 'eventbusDebugWidget' widget name.