Skip to content
Source
Sign inSign up
TanStack/devtools
Open History to see the last commit

devtools.tsx

307 lines7.6 KB

1import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
2import { render } from 'preact'
3import { TanStackDevtoolsCore } from '@tanstack/devtools'
4import type { JSX } from 'preact'
5import type {
6 ClientEventBusConfig,
7 TanStackDevtoolsConfig,
8 TanStackDevtoolsPlugin,
9 TanStackDevtoolsPluginProps,
10 TanStackDevtoolsTheme,
11} from '@tanstack/devtools'
12​
13type PluginRender =
14 | JSX.Element
15 | ((el: HTMLElement, props: TanStackDevtoolsPluginProps) => JSX.Element)
16​
17type TriggerProps = {
18 theme: TanStackDevtoolsTheme
20​
21type TriggerRender =
22 | JSX.Element
23 | ((el: HTMLElement, props: TriggerProps) => JSX.Element)
24​
25export type TanStackDevtoolsPreactPlugin = Omit<
26 TanStackDevtoolsPlugin,
27 'render' | 'name'
28> & {
29 /**
30 * The render function can be a Preact element or a function that returns a Preact element.
31 * If it's a function, it will be called to render the plugin, otherwise it will be rendered directly.
32 *
33 * Example:
34 * ```jsx
35 * {
36 * render: () => <CustomPluginComponent />,
37 * }
38 * ```
39 * or
40 * ```jsx
41 * {
42 * render: <CustomPluginComponent />,
43 * }
44 * ```
45 */
46 render: PluginRender
47 /**
48 * Name to be displayed in the devtools UI.
49 * If a string, it will be used as the plugin name.
50 * If a function, it will be called with the mount element.
51 *
52 * Example:
53 * ```jsx
54 * {
55 * name: "Your Plugin",
56 * render: () => <CustomPluginComponent />,
57 * }
58 * ```
59 * or
60 * ```jsx
61 * {
62 * name: <h1>Your Plugin title</h1>,
63 * render: () => <CustomPluginComponent />,
64 * }
65 * ```
66 */
67 name: string | PluginRender
69​
70type TanStackDevtoolsPreactConfig = Omit<
71 Partial<TanStackDevtoolsConfig>,
72 'customTrigger'
73> & {
74 /**
75 * Optional custom trigger component for the devtools.
76 * It can be a Preact element or a function that renders one.
77 *
78 * Example:
79 * ```jsx
80 * {
81 * customTrigger: <CustomTriggerComponent />,
82 * }
83 * ```
84 */
85 customTrigger?: TriggerRender
87​
88export interface TanStackDevtoolsPreactInit {
89 /**
90 * Array of plugins to be used in the devtools.
91 * Each plugin should have a `render` function that returns a Preact element or a function
92 *
93 * Example:
94 * ```jsx
95 * <TanStackDevtools
96 * plugins={[
97 * {
98 * id: "your-plugin-id",
99 * name: "Your Plugin",
100 * render: <CustomPluginComponent />,
101 * }
102 * ]}
103 * />
104 * ```
105 */
106 plugins?: Array<TanStackDevtoolsPreactPlugin>
107 /**
108 * Configuration for the devtools shell. These configuration options are used to set the
109 * initial state of the devtools when it is started for the first time. Afterwards,
110 * the settings are persisted in local storage and changed through the settings panel.
111 */
112 config?: TanStackDevtoolsPreactConfig
113 /**
114 * Configuration for the TanStack Devtools client event bus.
115 */
116 eventBusConfig?: ClientEventBusConfig
118​
119// Simple portal component for Preact
120function Portal({
121 children,
122 container,
123}: {
124 children: JSX.Element
125 container: HTMLElement
126}) {
127 useEffect(() => {
128 render(children, container)
129 return () => {
130 render(null, container)
131 }
132 }, [children, container])
133​
134 return null
136​
137const convertRender = (
138 Component: PluginRender,
139 setComponents: (
140 value:
141 | Record<string, JSX.Element>
142 | ((prev: Record<string, JSX.Element>) => Record<string, JSX.Element>),
143 ) => void,
144 e: HTMLElement,
145 props: TanStackDevtoolsPluginProps,
146) => {
147 const element =
148 typeof Component === 'function' ? Component(e, props) : Component
149​
150 setComponents((prev) => ({
151 ...prev,
152 [e.getAttribute('id') as string]: element,
153 }))
155​
156const convertTrigger = (
157 Component: TriggerRender,
158 setComponent: (component: JSX.Element | null) => void,
159 e: HTMLElement,
160 props: TriggerProps,
161) => {
162 const element =
163 typeof Component === 'function' ? Component(e, props) : Component
164 setComponent(element)
166​
167export const TanStackDevtools = ({
168 plugins,
169 config,
170 eventBusConfig,
171}: TanStackDevtoolsPreactInit): JSX.Element | null => {
172 const devToolRef = useRef<HTMLDivElement>(null)
173​
174 const [pluginContainers, setPluginContainers] = useState<
175 Record<string, HTMLElement>
176 >({})
177 const [titleContainers, setTitleContainers] = useState<
178 Record<string, HTMLElement>
179 >({})
180 const [triggerContainer, setTriggerContainer] = useState<HTMLElement | null>(
181 null,
182 )
183​
184 const [PluginComponents, setPluginComponents] = useState<
185 Record<string, JSX.Element>
186 >({})
187 const [TitleComponents, setTitleComponents] = useState<
188 Record<string, JSX.Element>
189 >({})
190 const [TriggerComponent, setTriggerComponent] = useState<JSX.Element | null>(
191 null,
192 )
193​
194 const pluginsMap: Array<TanStackDevtoolsPlugin> = useMemo(
195 () =>
196 plugins?.map((plugin) => {
197 return {
198 ...plugin,
199 name:
200 typeof plugin.name === 'string'
201 ? plugin.name
202 : (e, theme) => {
203 const id = e.getAttribute('id')!
204 const target = e.ownerDocument.getElementById(id)
205​
206 if (target) {
207 setTitleContainers((prev) => ({
208 ...prev,
209 [id]: e,
210 }))
211 }
212​
213 convertRender(
214 plugin.name as PluginRender,
215 setTitleComponents,
216 e,
217 theme,
218 )
219 },
220 render: (e, theme) => {
221 const id = e.getAttribute('id')!
222 const target = e.ownerDocument.getElementById(id)
223​
224 if (target) {
225 setPluginContainers((prev) => ({
226 ...prev,
227 [id]: e,
228 }))
229 }
230​
231 convertRender(plugin.render, setPluginComponents, e, theme)
232 },
233 }
234 }) ?? [],
235 [plugins],
236 )
237​
238 const [devtools] = useState(() => {
239 const { customTrigger, ...coreConfig } = config || {}
240 return new TanStackDevtoolsCore({
241 config: {
242 ...coreConfig,
243 customTrigger: customTrigger
244 ? (el, props) => {
245 setTriggerContainer(el)
246 convertTrigger(customTrigger, setTriggerComponent, el, props)
247 }
248 : undefined,
249 },
250 eventBusConfig,
251 plugins: pluginsMap,
252 })
253 })
254​
255 useEffect(() => {
256 devtools.setConfig({
257 plugins: pluginsMap,
258 })
259 }, [devtools, pluginsMap])
260​
261 useEffect(() => {
262 if (devToolRef.current) {
263 devtools.mount(devToolRef.current)
264 }
265​
266 return () => devtools.unmount()
267 }, [devtools])
268​
269 const hasPlugins =
270 Object.values(pluginContainers).length > 0 &&
271 Object.values(PluginComponents).length > 0
272 const hasTitles =
273 Object.values(titleContainers).length > 0 &&
274 Object.values(TitleComponents).length > 0
275​
276 return (
277 <>
278 <div style={{ position: 'absolute' }} ref={devToolRef} />
279​
280 {hasPlugins
281 ? Object.entries(pluginContainers).map(([key, pluginContainer]) => {
282 const component = PluginComponents[key]
283 return component ? (
284 <Portal key={key} container={pluginContainer}>
285 {component}
286 </Portal>
287 ) : null
288 })
289 : null}
290​
291 {hasTitles
292 ? Object.entries(titleContainers).map(([key, titleContainer]) => {
293 const component = TitleComponents[key]
294 return component ? (
295 <Portal key={key} container={titleContainer}>
296 {component}
297 </Portal>
298 ) : null
299 })
300 : null}
301​
302 {triggerContainer && TriggerComponent ? (
303 <Portal container={triggerContainer}>{TriggerComponent}</Portal>
304 ) : null}
305 </>
306 )