115 lines
4.7 KiB
Markdown
115 lines
4.7 KiB
Markdown
# Align Toolbar
|
|
|
|
- Status: stable
|
|
- Scope: persistent action bar alignment controls, selection handling, and current behavioral constraints
|
|
- Applies to: `web/js/align_panel.js`, `web/js/align_actions.js`, `web/js/align_panel.css`
|
|
- Source of truth level: feature
|
|
- Last verified commit: 9bb835c68f9a68ecccdbeae32bd41382a1eb3556
|
|
- Update when: action set, toolbar behavior, tooltip policy, selection policy, or mounting strategy changes
|
|
- Supersedes: none
|
|
- Superseded by: none
|
|
|
|
## Purpose
|
|
|
|
This subsystem owns the persistent alignment toolbar injected into the built-in ComfyUI action bar.
|
|
|
|
## Current scope
|
|
|
|
The current implementation provides:
|
|
|
|
- eight layout actions
|
|
- persistent mounting into the built-in action bar, to the left of the standard controls
|
|
- support for mixed selection of nodes, groups, and reroute dots
|
|
- native browser tooltip text using the button `title` attribute
|
|
- a small runtime diagnostics layer for upstream-drift detection
|
|
- flat frontend asset layout under `web/js/`
|
|
|
|
## Current action set
|
|
|
|
- Horizontal Align Left
|
|
- Horizontal Align Center
|
|
- Horizontal Align Right
|
|
- Horizontal Distribute Center
|
|
- Vertical Align Top
|
|
- Vertical Align Center
|
|
- Vertical Align Bottom
|
|
- Vertical Distribute Center
|
|
|
|
## Current important constraints
|
|
|
|
The current design intentionally does not:
|
|
|
|
- provide a toggleable panel UI
|
|
- provide hotkey-driven overlay behavior
|
|
- maintain disabled-state UI for insufficient selection
|
|
- use custom tooltip DOM or theme-specific tooltip components
|
|
- use a `web/js/align/` subfolder
|
|
|
|
## Current local code organization
|
|
|
|
- frontend DOM selectors and other frontend-sensitive anchors are centralized at the top of `align_panel.js`
|
|
- upstream type-name checks such as `LGraphGroup` and `Reroute` are centralized as constants
|
|
- action ids are centralized in the exported `ACTION_IDS` map in `align_actions.js`
|
|
- `ALIGN_ACTIONS` is built from `ACTION_IDS` so action ids are not duplicated across files
|
|
- runtime diagnostics stay local to `align_panel.js` rather than living in a separate shared file
|
|
|
|
## Behavioral notes
|
|
|
|
- align operations work on mixed selections of nodes, groups, and reroute dots
|
|
- center-distribute operations keep the first and last items in sorted axis order fixed and distribute the centers of the intermediate items evenly between them
|
|
- center-distribute operations are a no-op when fewer than three items are selected
|
|
- the toolbar mounts into `app.menu.element`, which ComfyUI hosts inside the upstream `legacy-topbar-container`
|
|
- the toolbar uses its own wrapper inside `app.menu.element`, keeping it in the same flex layout as other legacy menu groups
|
|
|
|
## Diagnostics behavior
|
|
|
|
The current implementation emits once-per-session console diagnostics when critical upstream assumptions stop matching the expected frontend or LiteGraph contract.
|
|
|
|
Current diagnostic codes include:
|
|
|
|
- `MOUNT_MENU_ELEMENT_MISSING`
|
|
- `MOUNT_ACTIONBAR_CONTAINER_MISSING`
|
|
- `MOUNT_REINSERT_FAILED`
|
|
- `CANVAS_CONTEXT_UNAVAILABLE`
|
|
- `SELECTION_MODEL_UNSUPPORTED`
|
|
- `GEOMETRY_UNAVAILABLE`
|
|
- `MOVEMENT_API_UNAVAILABLE`
|
|
- `CANVAS_REFRESH_API_UNAVAILABLE`
|
|
|
|
Diagnostics are intentionally grouped by assumption type rather than logged repeatedly for every occurrence.
|
|
|
|
## Upstream-sensitive touchpoints
|
|
|
|
This feature is currently sensitive to:
|
|
|
|
- the `app.menu.element` contract
|
|
- the placement of `app.menu.element` inside `legacy-topbar-container` in `TopMenuSection.vue`
|
|
- the surrounding `actionbar-container` structure used for observation and layout
|
|
- current LiteGraph selection containers (`selectedItems`, `selected_nodes`, `selected_group`)
|
|
- current geometry properties (`boundingRect`, `_bounding`, `bounding`, `pos`, `size`)
|
|
- current movement methods (`move`, `setPos`)
|
|
- current canvas refresh hooks (`setDirty`, `graph.change`)
|
|
|
|
## What not to do
|
|
|
|
- Do not reintroduce a more complex panel implementation unless the task explicitly requires it.
|
|
- Do not replace native `title` tooltips with a custom tooltip system casually.
|
|
- Do not move the current flat asset files back into a feature subfolder without a repository-level reason.
|
|
- Do not mount back into the Vue-managed child list inside `ComfyActionbar` unless the upstream integration model changes.
|
|
- Do not broaden DOM observation or long-lived selection caching without clear need.
|
|
- Do not replace the current once-per-session diagnostics with noisy per-occurrence console spam.
|
|
|
|
## Regression surface
|
|
|
|
Re-check this subsystem when changing:
|
|
|
|
- action bar insertion logic
|
|
- item type detection for groups or reroutes
|
|
- geometry extraction logic
|
|
- selection flattening for selected groups and descendants
|
|
- tooltip behavior
|
|
- the contract exported by `align_actions.js`
|
|
- center distribution behavior for mixed-size items
|
|
- the upstream `app.menu.element` / legacy topbar host contract
|
|
- diagnostic code meanings or reporting thresholds
|