mirror of https://github.com/Comfy-Org/ComfyUI_frontend.git synced 2026-01-26 19:09:52 +00:00

Files

Christian Byrne cf093d02a7 ADR: PrimeVue Fork Decision (#5230 )

* ADR: Add PrimeVue fork decision record

Adds ADR-0003 documenting the decision to fork PrimeVue as a monorepo workspace package. Key rationale includes transform coordinate system conflicts and virtual canvas scroll interference that require component-level modifications.

* ADR: Reject PrimeVue fork decision

- Change status from Proposed to Rejected
- Document rationale: implementation complexity with dual monorepos,
  maintenance burden, alternative solutions available
- Add specific code citations and repository links
- Include alternative approach using shadcn/ui for selective replacement

2025-09-12 23:06:28 -07:00

4.3 KiB

Raw Blame History

4. Fork PrimeVue UI Library

Date: 2025-08-27

Status

Rejected

Context

ComfyUI's frontend requires modifications to PrimeVue components that cannot be achieved through the library's customization APIs. Two specific technical incompatibilities have been identified with the transform-based canvas architecture:

Screen Coordinate Hit-Testing Conflicts:

PrimeVue components use getBoundingClientRect() for screen coordinate calculations that don't account for CSS transforms
The Slider component directly uses raw pageX/pageY coordinates (lines 102-103) without transform-aware positioning
This breaks interaction in transformed coordinate spaces where screen coordinates don't match logical element positions

Virtual Canvas Scroll Interference:

LiteGraph's infinite canvas uses scroll coordinates semantically for graph navigation via the DragAndScale coordinate system
PrimeVue overlay components automatically trigger scrollIntoView behavior which interferes with this virtual positioning
This issue is documented in PrimeVue discussion #4270 where the feature request was made to disable this behavior

Historical Overlay Issues:

Previous z-index positioning conflicts required manual workarounds (commit 6d4eafb0) where PrimeVue Dialog components needed autoZIndex: false and custom mask styling, later resolved by removing PrimeVue's automatic z-index management entirely

Minimal Update Overhead:

Analysis of git history shows only 2 PrimeVue version updates in 2+ years, indicating that upstream sync overhead is negligible for this project

Future Interaction System Requirements:

The ongoing canvas architecture evolution will require more granular control over component interaction and event handling as the transform-based system matures
Predictable need for additional component modifications beyond current identified issues

Decision

We will NOT fork PrimeVue. After evaluation, forking was determined to be unnecessarily complex and costly.

Rationale for Rejection:

Significant Implementation Complexity: PrimeVue is structured as a monorepo (primefaces/primevue) with significant code in a separate monorepo (PrimeUIX). Forking would require importing both repositories whole and selectively pruning or exempting components from our workspace tooling, adding substantial complexity.
Alternative Solutions Available: The modifications we identified (e.g., scroll interference issues, coordinate system conflicts) have less costly solutions that don't require maintaining a full fork. For example, coordinate issues could be addressed through event interception and synthetic event creation with scaled values.
Maintenance Burden: Ongoing maintenance and upgrades would be very painful, requiring manual conflict resolution and keeping pace with upstream changes across multiple repositories.
Limited Tooling Support: There isn't adequate tooling that provides the granularity needed to cleanly manage a PrimeVue fork within our existing infrastructure.

Consequences

Alternative Approach

Use PrimeVue as External Dependency: Continue using PrimeVue as a standard npm dependency
Targeted Workarounds: Implement specific solutions for identified issues (coordinate system conflicts, scroll interference) without forking the entire library
Selective Component Replacement: Use libraries like shadcn/ui to replace specific problematic PrimeVue components and adjust them to match our design system
Upstream Engagement: Continue engaging with PrimeVue community for feature requests and bug reports
Maintain Flexibility: Preserve ability to upgrade PrimeVue versions without fork maintenance overhead

Notes

Technical issues documented in the Context section remain valid concerns
Solutions will be pursued through targeted fixes rather than wholesale forking
Future re-evaluation possible if PrimeVue's architecture significantly changes or if alternative tooling becomes available
This decision prioritizes maintainability and development velocity over maximum customization control

4.3 KiB Raw Blame History