Line data Source code
1 : import type {
2 : ExecutableLGraphNode,
3 : LGraphCanvas,
4 : LGraphNode,
5 : CanvasPointer
6 : } from './entityRegistry'
7 : import type {
8 : Bounds,
9 : PointTuple as Point,
10 : SizeTuple as Size
11 : } from '@comfyorg/shared-frontend-utils/geometry'
12 : import type { CompositorWidgetValue } from './compositor'
13 : import type { CurveData } from './curve'
14 : import type { BoundingBox } from './boundingBoxes'
15 : import type { LightInfoEntry } from '@comfyorg/viewport3d/lightInfo/types'
16 : import type { WidgetValue } from './widgetValue'
17 : import type { WidgetId } from './widgetId'
18 : import type {
19 : WidgetSurfaces,
20 : WidgetVisibilityComponent
21 : } from './widgetVisibility'
22 : import type { ColorFormat } from './color'
23 : import type { InputSpec } from '@comfyorg/object-info-parser'
24 :
25 : import type { CanvasColour, ColorStop, RequiredProps } from './interfaces'
26 : import type { CanvasPointerEvent } from './events'
27 :
28 : export type { NodeBindable } from './nodeBindable'
29 :
30 2356 : export const CONFIG = Symbol()
31 2356 : export const GET_CONFIG = Symbol()
32 :
33 : /** Identifies the widget a slot is linked to. */
34 : export interface IWidgetLocator {
35 : name: string
36 : type?: string
37 : [CONFIG]?: InputSpec
38 : [GET_CONFIG]?: () => InputSpec | undefined
39 : }
40 :
41 : export interface IWidgetOptions<TValues = unknown> {
42 : on?: string
43 : off?: string
44 : max?: number
45 : min?: number
46 : slider_color?: CanvasColour
47 : marker_color?: CanvasColour
48 : precision?: number
49 : read_only?: boolean
50 : /**
51 : * @deprecated Use {@link IWidgetOptions.step2} instead.
52 : * The legacy step is scaled up by 10x in the legacy frontend logic.
53 : */
54 : step?: number
55 : /** The step value for numeric widgets. */
56 : step2?: number
57 :
58 : y?: number
59 : multiline?: boolean
60 : // TODO: Confirm this
61 : property?: string
62 : /** If `true`, an input socket will not be created for this widget. */
63 : socketless?: boolean
64 : surfaces?: WidgetSurfaces
65 : /** @deprecated This key stays supported for third-party widgets. */
66 : canvasOnly?: boolean
67 : /**
68 : * If `true`, the widget still renders on the node but is omitted from the
69 : * right side panel. Unlike {@link IWidgetOptions.canvasOnly}, the node body
70 : * keeps rendering it via the Vue renderer. Used for widgets that hold
71 : * non-syncable state (e.g. a Three.js viewport) where a second instance in
72 : * the panel would diverge from the one on the node.
73 : */
74 : hideInPanel?: boolean
75 : /** Used as a temporary override for determining the asset type in vue mode*/
76 : nodeType?: string
77 :
78 : /**
79 : * Whether the widget value should be included in the API prompt sent to
80 : * the backend for execution. Checked by {@link executionUtil} when
81 : * building the prompt payload.
82 : *
83 : * This is distinct from {@link IBaseWidget.serialize}, which controls
84 : * whether the value is persisted in the workflow JSON file.
85 : *
86 : * @default true
87 : * @see IBaseWidget.serialize — workflow persistence
88 : */
89 : serialize?: boolean
90 : /**
91 : * Rounding value for numeric float widgets.
92 : */
93 : round?: number
94 : /**
95 : * The minimum size of the node if the widget is present.
96 : */
97 : minNodeSize?: Size
98 :
99 : advanced?: boolean
100 :
101 : values?: TValues
102 : /** Optional function to format values for display (e.g., hash → human-readable name) */
103 : getOptionLabel?: (value?: string | null) => string
104 : callback?: IWidget['callback']
105 : iconClass?: string
106 :
107 : // Vue widget options
108 : disabled?: boolean
109 : useGrouping?: boolean
110 : placeholder?: string
111 : hidden?: boolean
112 : }
113 :
114 : interface IWidgetSliderOptions extends IWidgetOptions<number[]> {
115 : min: number
116 : max: number
117 : step2: number
118 : slider_color?: CanvasColour
119 : marker_color?: CanvasColour
120 : }
121 :
122 : export interface IWidgetGradientSliderOptions extends IWidgetOptions<number[]> {
123 : min: number
124 : max: number
125 : step2: number
126 : gradient_stops?: ColorStop[]
127 : }
128 :
129 : interface IWidgetKnobOptions extends IWidgetOptions<number[]> {
130 : min: number
131 : max: number
132 : step2: number
133 : slider_color?: CanvasColour // TODO: Replace with knob color
134 : marker_color?: CanvasColour
135 : gradient_stops?: string
136 : }
137 :
138 : export interface IWidgetAssetOptions extends IWidgetOptions {
139 : openModal: (widget: IBaseWidget) => void
140 : }
141 :
142 : /**
143 : * A widget for a node.
144 : * All types are based on IBaseWidget - additions can be made there or directly on individual types.
145 : *
146 : * Implemented as a discriminative union of widget types, so this type itself cannot be extended.
147 : * Recommend declaration merging any properties that use IWidget (e.g. {@link LGraphNode.widgets}) with a new type alias.
148 : * @see ICustomWidget
149 : */
150 : export type IWidget =
151 : | IBooleanWidget
152 : | INumericWidget
153 : | IStringWidget
154 : | IComboWidget
155 : | IStringComboWidget
156 : | ICustomWidget
157 : | ISliderWidget
158 : | IGradientSliderWidget
159 : | IButtonWidget
160 : | IKnobWidget
161 : | IFileUploadWidget
162 : | IColorWidget
163 : | IMarkdownWidget
164 : | IImageWidget
165 : | ITreeSelectWidget
166 : | IMultiSelectWidget
167 : | IChartWidget
168 : | IGalleriaWidget
169 : | IImageCompareWidget
170 : | ISelectButtonWidget
171 : | ITextareaWidget
172 : | IAssetWidget
173 : | IImageCropWidget
174 : | IBoundingBoxWidget
175 : | ICurveWidget
176 : | IPainterWidget
177 : | ICompositorWidget
178 : | IRangeWidget
179 : | IVideoEditWidget
180 : | IVideoConcatWidget
181 : | IResolutionPreviewWidget
182 : | IBoundingBoxesWidget
183 : | ILightInfoWidget
184 : | IColorsWidget
185 :
186 : export interface IBooleanWidget extends IBaseWidget<boolean, 'toggle'> {
187 : type: 'toggle'
188 : value: boolean
189 : }
190 :
191 : /** Any widget that uses a numeric backing */
192 : export interface INumericWidget extends IBaseWidget<number, 'number'> {
193 : type: 'number'
194 : value: number
195 : }
196 :
197 : export interface ISliderWidget extends IBaseWidget<
198 : number,
199 : 'slider',
200 : IWidgetSliderOptions
201 : > {
202 : type: 'slider'
203 : value: number
204 : marker?: number
205 : }
206 :
207 : export interface IGradientSliderWidget extends IBaseWidget<
208 : number,
209 : 'gradientslider',
210 : IWidgetGradientSliderOptions
211 : > {
212 : type: 'gradientslider'
213 : value: number
214 : }
215 :
216 : export interface IKnobWidget extends IBaseWidget<
217 : number,
218 : 'knob',
219 : IWidgetKnobOptions
220 : > {
221 : type: 'knob'
222 : value: number
223 : options: IWidgetKnobOptions
224 : }
225 :
226 : /** Avoids the type issues with the legacy IComboWidget type */
227 : export interface IStringComboWidget extends IBaseWidget<
228 : string,
229 : 'combo',
230 : RequiredProps<IWidgetOptions<string[]>, 'values'>
231 : > {
232 : type: 'combo'
233 : value: string
234 : }
235 :
236 : export type ComboWidgetValues =
237 : | (string | number)[]
238 : | Record<string, string>
239 : | ((widget?: IComboWidget, node?: LGraphNode) => (string | number)[])
240 :
241 : /** A combo-box widget (dropdown, select, etc) */
242 : export interface IComboWidget extends IBaseWidget<
243 : string | number,
244 : 'combo',
245 : RequiredProps<IWidgetOptions<ComboWidgetValues>, 'values'>
246 : > {
247 : type: 'combo'
248 : value: string | number
249 : }
250 :
251 : /** A widget with a string value */
252 : export interface IStringWidget extends IBaseWidget<
253 : string,
254 : 'string' | 'text',
255 : IWidgetOptions<string[]>
256 : > {
257 : type: 'string' | 'text'
258 : value: string
259 : }
260 :
261 : export interface IButtonWidget extends IBaseWidget<
262 : string | undefined,
263 : 'button'
264 : > {
265 : type: 'button'
266 : value: string | undefined
267 : clicked: boolean
268 : }
269 :
270 : /** A custom widget - accepts any value and has no built-in special handling */
271 : interface ICustomWidget extends IBaseWidget<string | object, 'custom'> {
272 : type: 'custom'
273 : value: string | object
274 : }
275 :
276 : /** File upload widget for selecting and uploading files */
277 : export interface IFileUploadWidget extends IBaseWidget<string, 'fileupload'> {
278 : type: 'fileupload'
279 : value: string
280 : label?: string
281 : }
282 :
283 : /** Color picker widget for selecting colors */
284 : export interface IColorWidgetOptions extends IWidgetOptions {
285 : format?: ColorFormat | 'int'
286 : }
287 :
288 : export interface IColorWidget extends IBaseWidget<
289 : string | number,
290 : 'color',
291 : IColorWidgetOptions
292 : > {
293 : type: 'color'
294 : value: string | number
295 : }
296 :
297 : /** Markdown widget for displaying formatted text */
298 : export interface IMarkdownWidget extends IBaseWidget<string, 'markdown'> {
299 : type: 'markdown'
300 : value: string
301 : }
302 :
303 : /** Image display widget */
304 : interface IImageWidget extends IBaseWidget<string, 'image'> {
305 : type: 'image'
306 : value: string
307 : }
308 :
309 : /** Tree select widget for hierarchical selection */
310 : export interface ITreeSelectWidget extends IBaseWidget<
311 : string | string[],
312 : 'treeselect'
313 : > {
314 : type: 'treeselect'
315 : value: string | string[]
316 : }
317 :
318 : /** Multi-select widget for selecting multiple options */
319 : export interface IMultiSelectWidget extends IBaseWidget<
320 : string[],
321 : 'multiselect'
322 : > {
323 : type: 'multiselect'
324 : value: string[]
325 : }
326 :
327 : /** Chart widget for displaying data visualizations */
328 : export interface IChartWidget extends IBaseWidget<object, 'chart'> {
329 : type: 'chart'
330 : value: object
331 : }
332 :
333 : /** Gallery widget for displaying multiple images */
334 : export interface IGalleriaWidget extends IBaseWidget<string[], 'galleria'> {
335 : type: 'galleria'
336 : value: string[]
337 : }
338 :
339 : /** Image comparison widget for comparing two images side by side */
340 : export interface IImageCompareWidget extends IBaseWidget<
341 : string[],
342 : 'imagecompare'
343 : > {
344 : type: 'imagecompare'
345 : value: string[]
346 : }
347 :
348 : /** Select button widget for selecting from a group of buttons */
349 : export interface ISelectButtonWidget extends IBaseWidget<
350 : string,
351 : 'selectbutton',
352 : RequiredProps<IWidgetOptions<string[]>, 'values'>
353 : > {
354 : type: 'selectbutton'
355 : value: string
356 : }
357 :
358 : /** Textarea widget for multi-line text input */
359 : export interface ITextareaWidget extends IBaseWidget<string, 'textarea'> {
360 : type: 'textarea'
361 : value: string
362 : }
363 :
364 : export interface IAssetWidget extends IBaseWidget<
365 : string,
366 : 'asset',
367 : IWidgetAssetOptions
368 : > {
369 : type: 'asset'
370 : value: string
371 : }
372 :
373 : /** Image crop widget for cropping image */
374 : export interface IImageCropWidget extends IBaseWidget<Bounds, 'imagecrop'> {
375 : type: 'imagecrop'
376 : value: Bounds
377 : }
378 :
379 : /** Bounding box widget for defining regions with numeric inputs */
380 : export interface IBoundingBoxWidget extends IBaseWidget<Bounds, 'boundingbox'> {
381 : type: 'boundingbox'
382 : value: Bounds
383 : }
384 :
385 : export interface ICurveWidget extends IBaseWidget<CurveData, 'curve'> {
386 : type: 'curve'
387 : value: CurveData
388 : }
389 :
390 : export interface IPainterWidget extends IBaseWidget<string, 'painter'> {
391 : type: 'painter'
392 : value: string
393 : }
394 :
395 : export interface ICompositorWidget extends IBaseWidget<
396 : CompositorWidgetValue,
397 : 'compositor'
398 : > {
399 : type: 'compositor'
400 : value: CompositorWidgetValue
401 : }
402 :
403 : export interface IWidgetBoundingBoxesOptions extends IWidgetOptions {
404 : max_boxes?: number
405 : }
406 :
407 : export interface IBoundingBoxesWidget extends IBaseWidget<
408 : BoundingBox[],
409 : 'boundingboxes',
410 : IWidgetBoundingBoxesOptions
411 : > {
412 : type: 'boundingboxes'
413 : value: BoundingBox[]
414 : }
415 :
416 : export interface ILightInfoWidget extends IBaseWidget<
417 : LightInfoEntry[],
418 : 'lightinfo'
419 : > {
420 : type: 'lightinfo'
421 : value: LightInfoEntry[]
422 : }
423 :
424 : export interface IColorsWidget extends IBaseWidget<string[], 'colors'> {
425 : type: 'colors'
426 : value: string[]
427 : }
428 :
429 : export interface RangeValue {
430 : min: number
431 : max: number
432 : midpoint?: number
433 : }
434 :
435 : export interface IWidgetRangeOptions extends IWidgetOptions {
436 : display?: 'plain' | 'gradient' | 'histogram'
437 : gradient_stops?: ColorStop[]
438 : show_midpoint?: boolean
439 : midpoint_scale?: 'linear' | 'gamma'
440 : value_min?: number
441 : value_max?: number
442 : }
443 :
444 : export interface IRangeWidget extends IBaseWidget<
445 : RangeValue,
446 : 'range',
447 : IWidgetRangeOptions
448 : > {
449 : type: 'range'
450 : value: RangeValue
451 : }
452 :
453 : export interface VideoEditTrim {
454 : start_time: number
455 : duration: number
456 : }
457 :
458 : export interface VideoEditValue {
459 : trim?: VideoEditTrim
460 : crop?: Bounds
461 : }
462 :
463 : export type VideoEditFeature = 'trim' | 'crop'
464 :
465 : export interface IWidgetVideoEditOptions extends IWidgetOptions {
466 : features?: VideoEditFeature[]
467 : }
468 :
469 : export interface IVideoEditWidget extends IBaseWidget<
470 : VideoEditValue,
471 : 'videoedit',
472 : IWidgetVideoEditOptions
473 : > {
474 : type: 'videoedit'
475 : value: VideoEditValue
476 : }
477 :
478 : export interface VideoConcatValue {
479 : order?: string[]
480 : }
481 :
482 : export interface IWidgetVideoConcatOptions extends IWidgetOptions {
483 : source: string
484 : }
485 :
486 : export interface IVideoConcatWidget extends IBaseWidget<
487 : VideoConcatValue,
488 : 'videoconcat',
489 : IWidgetVideoConcatOptions
490 : > {
491 : type: 'videoconcat'
492 : value: VideoConcatValue
493 : }
494 :
495 : export interface IWidgetResolutionPreviewOptions extends IWidgetOptions {
496 : ratio_widget?: string
497 : megapixels_widget?: string
498 : multiple_widget?: string
499 : }
500 :
501 : export interface IResolutionPreviewWidget extends IBaseWidget<
502 : null,
503 : 'resolutionpreview',
504 : IWidgetResolutionPreviewOptions
505 : > {
506 : type: 'resolutionpreview'
507 : value: null
508 : }
509 :
510 : /**
511 : * Valid widget types. TS cannot provide easily extensible type safety for this at present.
512 : * Override linkedWidgets[]
513 : * Values not in this list will not result in litegraph errors, however they will be treated the same as "custom".
514 : */
515 : export type TWidgetType = IWidget['type']
516 : export type TWidgetValue = WidgetValue
517 :
518 3014 : export function isWidgetValue(value: unknown): value is TWidgetValue {
519 3014 : if (value == null) return true
520 3014 : if (typeof value === 'string') return true
521 1316 : if (typeof value === 'number') return true
522 86 : if (typeof value === 'boolean') return true
523 0 : return typeof value === 'object'
524 : }
525 :
526 : export interface WidgetCallbackOptions {
527 : isPartialExecution?: boolean
528 : }
529 :
530 : /**
531 : * The base type for all widgets. Should not be implemented directly.
532 : * @template TValue The type of value this widget holds.
533 : * @template TType A string designating the type of widget, e.g. "toggle" or "string".
534 : * @template TOptions The options for this widget.
535 : * @see IWidget
536 : */
537 : export interface IBaseWidget<
538 : TValue = WidgetValue,
539 : TType extends string = string,
540 : TOptions extends IWidgetOptions = IWidgetOptions
541 : > {
542 : [symbol: symbol]: boolean
543 :
544 : linkedWidgets?: IBaseWidget[]
545 :
546 : readonly widgetId?: WidgetId
547 :
548 : name: string
549 : options: TOptions
550 : syncLiveVisibilityOptions?(): void
551 : syncLiveDisabled?(): void
552 :
553 : label?: string
554 : /** Widget type (see {@link TWidgetType}) */
555 : type: TType
556 : value?: TValue
557 :
558 : /**
559 : * Whether the widget value is persisted in the workflow JSON
560 : * (`widgets_values`). Checked by {@link LGraphNode.serialize} and
561 : * {@link LGraphNode.configure}.
562 : *
563 : * This is distinct from {@link IWidgetOptions.serialize}, which controls
564 : * whether the value is included in the API prompt sent for execution.
565 : *
566 : * @default true
567 : * @see IWidgetOptions.serialize — API prompt inclusion
568 : */
569 : serialize?: boolean
570 :
571 : /**
572 : * The computed height of the widget. Used by customized node resize logic.
573 : * See scripts/domWidget.ts for more details.
574 : * @readonly [Computed] This property is computed by the node.
575 : */
576 : computedHeight?: number
577 :
578 : /**
579 : * The starting y position of the widget after layout.
580 : * @readonly [Computed] This property is computed by the node.
581 : */
582 : y: number
583 :
584 : /**
585 : * The y position of the widget after drawing (rendering).
586 : * @readonly [Computed] This property is computed by the node.
587 : * @deprecated There is no longer dynamic y adjustment on rendering anymore.
588 : * Use {@link IBaseWidget.y} instead.
589 : */
590 : last_y?: number
591 :
592 : width?: number
593 : /**
594 : * Whether the widget is disabled. Disabled widgets are rendered at half opacity.
595 : * See also {@link IBaseWidget.computedDisabled}.
596 : */
597 : disabled?: boolean
598 :
599 : /**
600 : * The disabled state used for rendering based on various conditions including
601 : * {@link IBaseWidget.disabled}.
602 : * @readonly [Computed] This property is computed by the node.
603 : */
604 : computedDisabled?: boolean
605 :
606 : /**
607 : * Whether the widget's input is satisfied by an upstream link, suppressing
608 : * the widget on every rendering surface (the slot still renders).
609 : * @readonly [Computed] This property is computed by the node on
610 : * connection changes.
611 : */
612 : connectionSuppressed?: boolean
613 :
614 : hidden?: boolean
615 : advanced?: boolean
616 :
617 : /**
618 : * Canonical visibility component backing the `hidden` / `advanced` /
619 : * `options.hideInPanel` facades. Present on concrete widgets; absent on
620 : * legacy POJO widgets that have not been adopted yet.
621 : */
622 : readonly visibility?: WidgetVisibilityComponent
623 :
624 : tooltip?: string
625 :
626 : // TODO: Confirm this format
627 : callback?(
628 : value: WidgetValue,
629 : canvas?: LGraphCanvas,
630 : node?: LGraphNode,
631 : pos?: Point,
632 : e?: CanvasPointerEvent
633 : ): void
634 :
635 : /**
636 : * Simple callback for pointer events, allowing custom widgets to events relevant to them.
637 : * @param event The pointer event that triggered this callback
638 : * @param pointerOffset Offset of the pointer relative to {@link node.pos}
639 : * @param node The node this widget belongs to
640 : * @todo Expose CanvasPointer API to custom widgets
641 : */
642 : mouse?(
643 : event: CanvasPointerEvent,
644 : pointerOffset: Point,
645 : node: LGraphNode
646 : ): boolean
647 : /**
648 : * Draw the widget.
649 : * @param ctx The canvas context to draw on.
650 : * @param node The node this widget belongs to.
651 : * @param widget_width The width of the widget.
652 : * @param y The y position of the widget.
653 : * @param H The height of the widget.
654 : * @param lowQuality Whether to draw the widget in low quality.
655 : */
656 : draw?(
657 : ctx: CanvasRenderingContext2D,
658 : node: LGraphNode,
659 : widget_width: number,
660 : y: number,
661 : H: number,
662 : lowQuality?: boolean
663 : ): void
664 :
665 : /**
666 : * Compatibility method for widgets implementing the draw
667 : * method when displayed in non-canvas renderers.
668 : * Set by the current renderer implementation.
669 : * When called, performs a draw operation.
670 : */
671 : triggerDraw?: () => void
672 :
673 : /**
674 : * Compute the size of the widget. Overrides {@link IBaseWidget.computeSize}.
675 : * @param width The width of the widget.
676 : * @deprecated Use {@link IBaseWidget.computeLayoutSize} instead.
677 : * @returns The size of the widget.
678 : */
679 : computeSize?(width?: number): Size
680 :
681 : /**
682 : * Compute the layout size of the widget.
683 : * @param node The node this widget belongs to.
684 : * @returns The layout size of the widget.
685 : */
686 : computeLayoutSize?(
687 : this: IBaseWidget,
688 : node: LGraphNode
689 : ): {
690 : minHeight: number
691 : maxHeight?: number
692 : minWidth: number
693 : maxWidth?: number
694 : }
695 :
696 : /**
697 : * Callback for pointerdown events, allowing custom widgets to register callbacks to occur
698 : * for all {@link CanvasPointer} events.
699 : *
700 : * This callback is operated early in the pointerdown logic; actions that prevent it from firing are:
701 : * - `Ctrl + Drag` Multi-select
702 : * - `Alt + Click/Drag` Clone node
703 : * @param pointer The CanvasPointer handling this event
704 : * @param node The node this widget belongs to
705 : * @param canvas The LGraphCanvas where this event originated
706 : * @returns Returning `true` from this callback forces Litegraph to ignore the event and
707 : * not process it any further.
708 : */
709 : onPointerDown?(
710 : pointer: CanvasPointer,
711 : node: LGraphNode,
712 : canvas: LGraphCanvas
713 : ): boolean
714 :
715 : onRemove?(): void
716 : beforeQueued?(options?: WidgetCallbackOptions): unknown
717 : afterQueued?(options?: WidgetCallbackOptions): unknown
718 : serializeValue?(
719 : node: ExecutableLGraphNode | LGraphNode,
720 : index: number
721 : ): unknown
722 :
723 : /**
724 : * Refreshes the widget's value or options from its remote source.
725 : */
726 : refresh?(): unknown
727 :
728 : dynamicPrompts?: boolean
729 : }
|