1 | import { IDisposable } from '@lumino/disposable';
|
2 | import { Message } from '@lumino/messaging';
|
3 | import { ISignal, Signal } from '@lumino/signaling';
|
4 | import { Widget } from '@lumino/widgets';
|
5 | import * as React from 'react';
|
6 | declare type ReactRenderElement = Array<React.ReactElement<any>> | React.ReactElement<any>;
|
7 | /**
|
8 | * An abstract class for a Phosphor widget which renders a React component.
|
9 | */
|
10 | export declare abstract class ReactWidget extends Widget {
|
11 | /**
|
12 | * Creates a new `ReactWidget` that renders a constant element.
|
13 | * @param element React element to render.
|
14 | */
|
15 | static create(element: ReactRenderElement): ReactWidget;
|
16 | /**
|
17 | * Render the content of this widget using the virtual DOM.
|
18 | *
|
19 | * This method will be called anytime the widget needs to be rendered, which
|
20 | * includes layout triggered rendering.
|
21 | *
|
22 | * Subclasses should define this method and return the root React nodes here.
|
23 | */
|
24 | protected abstract render(): ReactRenderElement | null;
|
25 | /**
|
26 | * Called to update the state of the widget.
|
27 | *
|
28 | * The default implementation of this method triggers
|
29 | * VDOM based rendering by calling the `renderDOM` method.
|
30 | */
|
31 | protected onUpdateRequest(msg: Message): void;
|
32 | /**
|
33 | * Called after the widget is attached to the DOM
|
34 | */
|
35 | protected onAfterAttach(msg: Message): void;
|
36 | /**
|
37 | * Called before the widget is detached from the DOM.
|
38 | */
|
39 | protected onBeforeDetach(msg: Message): void;
|
40 | /**
|
41 | * Render the React nodes to the DOM.
|
42 | *
|
43 | * @returns a promise that resolves when the rendering is done.
|
44 | */
|
45 | private renderDOM;
|
46 | renderPromise?: Promise<void>;
|
47 | }
|
48 | /**
|
49 | * An abstract ReactWidget with a model.
|
50 | */
|
51 | export declare abstract class VDomRenderer<T extends VDomRenderer.IModel | null = null> extends ReactWidget {
|
52 | /**
|
53 | * Create a new VDomRenderer
|
54 | */
|
55 | constructor(model: T extends null ? void : T);
|
56 | /**
|
57 | * A signal emitted when the model changes.
|
58 | */
|
59 | get modelChanged(): ISignal<this, void>;
|
60 | /**
|
61 | * Set the model and fire changed signals.
|
62 | */
|
63 | set model(newValue: T);
|
64 | /**
|
65 | * Get the current model.
|
66 | */
|
67 | get model(): T;
|
68 | /**
|
69 | * Dispose this widget.
|
70 | */
|
71 | dispose(): void;
|
72 | private _model;
|
73 | private _modelChanged;
|
74 | }
|
75 | /**
|
76 | * Props for the UseSignal component
|
77 | */
|
78 | export interface IUseSignalProps<SENDER, ARGS> {
|
79 | /**
|
80 | * Phosphor signal to connect to.
|
81 | */
|
82 | signal: ISignal<SENDER, ARGS>;
|
83 | /**
|
84 | * Initial value to use for the sender, used before the signal emits a value.
|
85 | * If not provided, initial sender will be undefined
|
86 | */
|
87 | initialSender?: SENDER;
|
88 | /**
|
89 | * Initial value to use for the args, used before the signal emits a value.
|
90 | * If not provided, initial args will be undefined.
|
91 | */
|
92 | initialArgs?: ARGS;
|
93 | /**
|
94 | * Function mapping the last signal value or initial values to an element to render.
|
95 | *
|
96 | * Note: returns `React.ReactNode` as per
|
97 | * https://github.com/sw-yx/react-typescript-cheatsheet#higher-order-componentsrender-props
|
98 | */
|
99 | children: (sender?: SENDER, args?: ARGS) => React.ReactNode;
|
100 | /**
|
101 | * Given the last signal value, should return whether to update the state or not.
|
102 | *
|
103 | * The default unconditionally returns `true`, so you only have to override if you want
|
104 | * to skip some updates.
|
105 | */
|
106 | shouldUpdate?: (sender: SENDER, args: ARGS) => boolean;
|
107 | }
|
108 | /**
|
109 | * State for the UseSignal component
|
110 | */
|
111 | export interface IUseSignalState<SENDER, ARGS> {
|
112 | value: [SENDER?, ARGS?];
|
113 | }
|
114 | /**
|
115 | * UseSignal provides a way to hook up a Phosphor signal to a React element,
|
116 | * so that the element is re-rendered every time the signal fires.
|
117 | *
|
118 | * It is implemented through the "render props" technique, using the `children`
|
119 | * prop as a function to render, so that it can be used either as a prop or as a child
|
120 | * of this element
|
121 | * https://reactjs.org/docs/render-props.html
|
122 | *
|
123 | *
|
124 | * Example as child:
|
125 | *
|
126 | * ```
|
127 | * function LiveButton(isActiveSignal: ISignal<any, boolean>) {
|
128 | * return (
|
129 | * <UseSignal signal={isActiveSignal} initialArgs={True}>
|
130 | * {(_, isActive) => <Button isActive={isActive}>}
|
131 | * </UseSignal>
|
132 | * )
|
133 | * }
|
134 | * ```
|
135 | *
|
136 | * Example as prop:
|
137 | *
|
138 | * ```
|
139 | * function LiveButton(isActiveSignal: ISignal<any, boolean>) {
|
140 | * return (
|
141 | * <UseSignal
|
142 | * signal={isActiveSignal}
|
143 | * initialArgs={True}
|
144 | * children={(_, isActive) => <Button isActive={isActive}>}
|
145 | * />
|
146 | * )
|
147 | * }
|
148 | * ```
|
149 | */
|
150 | export declare class UseSignal<SENDER, ARGS> extends React.Component<IUseSignalProps<SENDER, ARGS>, IUseSignalState<SENDER, ARGS>> {
|
151 | constructor(props: IUseSignalProps<SENDER, ARGS>);
|
152 | componentDidMount(): void;
|
153 | componentWillUnmount(): void;
|
154 | private slot;
|
155 | render(): React.ReactNode;
|
156 | }
|
157 | /**
|
158 | * The namespace for VDomRenderer statics.
|
159 | */
|
160 | export declare namespace VDomRenderer {
|
161 | /**
|
162 | * An interface for a model to be used with vdom rendering.
|
163 | */
|
164 | interface IModel extends IDisposable {
|
165 | /**
|
166 | * A signal emitted when any model state changes.
|
167 | */
|
168 | readonly stateChanged: ISignal<this, void>;
|
169 | }
|
170 | }
|
171 | /**
|
172 | * Concrete implementation of VDomRenderer model.
|
173 | */
|
174 | export declare class VDomModel implements VDomRenderer.IModel {
|
175 | /**
|
176 | * A signal emitted when any model state changes.
|
177 | */
|
178 | readonly stateChanged: Signal<this, void>;
|
179 | /**
|
180 | * Test whether the model is disposed.
|
181 | */
|
182 | get isDisposed(): boolean;
|
183 | /**
|
184 | * Dispose the model.
|
185 | */
|
186 | dispose(): void;
|
187 | private _isDisposed;
|
188 | }
|
189 | export {};
|