@wuespace/telestion-client-common
Install using
npm install @wuespace/telestion-client-common
You can access these members by importing the module:
import { member } from '@wuespace/telestion-client-common';
function ContextMenu (...)
interface ContextMenuProps
function ContextMenuProvider (...)
interface ContextMenuProviderProps
function ContextMenuWrapper (...)
interface ContextMenuWrapperProps
function useLogo (...)
function useWidgets (...)
function AccountControls (...)
function Actions (...)
identifier Actions
interface ActionsProps
function ActionDivider (...)
function ColorSchemeAction (...)
function NotificationAction (...)
function FullscreenAction (...)
function DashboardPicker (...)
function NavBar (...)
identifier NavBar
interface NavBarProps
function AppLogo (...)
function ConnectionIndicator (...)
function Header (...)
identifier Header
interface HeaderProps
function DashboardPage (...)
identifier DashboardPage
function LoginForm (...)
interface LoginFormProps
function LoginDescription (...)
interface LoginDescriptionProps
function LoginLogo (...)
function LoginPage (...)
identifier LoginPage
interface LoginPageProps
function LoginTitle (...)
function NotFoundPage (...)
identifier NotFoundPage
function LoadingIndicator (...)
interface LoadingIndicatorProps
function OverflowFix (...)
interface OverflowFixProps
function CommonWrapper (...)
interface CommonWrapperProps
function useCurrentDashboards (...)
function useDarkColorScheme (...)
function useDashboards (...)
type DispatchDashboards
variable useColorScheme
function showDialog (...)
variable useDialog
variable useUserConfig
type ColorScheme
interface ColorSchemeState
type CallableComponent
interface DialogConfig
interface Dialog
interface DialogState
interface UserConfigState
function useBooleanState (...)
type InitialState
type ReturnType
function useEvent (...)
function useStoredState (...)
function useDependencyTimeout (...)
function useSpectrumColor (...)
function useDesktopNotifications (...)
type Optional
type SetPartialStateAction
type Undefinable
type StaticColorMap
type ColorMap
variable staticColors
variable lightColors
variable darkColors
function isDefinedValue (...)
variable commonWidgets
variable eventbusDebugWidget
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
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
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
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.
useLogo (...)
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>
}
/>
);
}
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
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} />}
/>
);
}
NavBar
NavBarProps
interface
NavBarProps
React Props of NavBar
For more information about React Props, please look here:
https://reactjs.org/docs/components-and-props.html
links ?
Type:
Array<Link>
Links to display in a tab list. If no links are set the application are shown.
@see:
AppLogo (...)
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.
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 />
</>
}
/>
);
}
Header
HeaderProps
interface
HeaderProps
React Props of Header
For more information about React Props, please look here:
https://reactjs.org/docs/components-and-props.html
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>
);
}
DashboardPage
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
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
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.
LoginLogo (...)
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:
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;
LoginPage
LoginPageProps
interface
LoginPageProps
React Props of LoginPageProps
For more information about React Props, please look here:
https://reactjs.org/docs/components-and-props.html
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>
);
}
NotFoundPage
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:
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<any>
React Props of OverflowFix
For more information about React Props, please look here:
https://reactjs.org/docs/components-and-props.html
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
appLogo ?
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:
ReactNode
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
:
UseBoundStore<StoreApi<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 the 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
:
UseBoundStore<StoreApi<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
:
UseBoundStore<StoreApi<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 valid color scheme:
light
- use always the light themedark
- use always the dark themesystem
- use the system defined colorscheme
ColorSchemeState
interface
ColorSchemeState
The color scheme store and actions of Telestion Client Common.
Stores and handles the current color scheme of the application.
colorScheme
Type:
ColorScheme
The current color scheme of the application.
@see:
set
Type:
(colorScheme: ColorScheme) => void
Sets a new color scheme for the application.
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
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
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 returns
onCancel
Type:
() => void
A handler to cancel the opened dialog.
DialogState
interface
DialogState
The dialog store and actions of Telestion Client Common.
Stores and handles show dialog calls from projects and common itself.
@see:
dialogs
Type:
Array<Dialog<any>>
Stores the currently registered dialogs.
@see:
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
The user configs store and actions of Telestion Client Common.
Stores and handles user configurations.
@see:
@see:
@see:
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.
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
useDesktopNotifications (...)
function useDesktopNotifications
(
)
:
void
Enables and handles the usage of native desktop notifications for implementing the
@wuespace/telestion-client-core
's abstract useNotifications
APIs.
Call this hook once in your app.tsx
and everything else gets handled for you.
@see:
@example:
// [...]
import { useDesktopNotifications } from '@wuespace/telestion-client-common';
export function App() {
useDesktopNotifications();
useEventBusManager();
// [...]
return <TelestionClient>
// [...]
</TelestionClient>
}
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.
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.
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
eventbusDebugWidget
const
:
Widget
A widget that show's debug information about the eventbus connection.
It's accessible via the 'eventbusDebugWidget'
widget name.