# Operad 7.0 Migration Guide
This document tracks the public API policy for the v7 roadmap. It is intentionally
started before all v7 work is complete so breaking changes, aliases, and
preferred imports are captured as they happen instead of reconstructed at
release time.
## Compatibility Policy
V7 should keep customer-facing churn deliberate:
- Prefer the grouped public modules for new code:
`operad::core`, `operad::interaction`, `operad::render`, `operad::runtime`,
`operad::adapters`, `operad::accessibility`, `operad::widgets`,
`operad::theme`, `operad::diagnostics`, and `operad::prelude`.
- Keep extremely common v6 root exports when they are cheap and clear.
- Keep old flat module aliases for one major cycle when removing them would not
simplify the API materially.
- Deprecate misleading paths before removing them when possible.
- Break paths immediately only when the old path leaks backend-specific details
into backend-neutral code, hides feature-gated dependencies, or teaches the
wrong ownership model.
## Preferred Imports
New application code can start with:
```rust
use operad::prelude::*;
```
Use module imports when a surface needs a narrower contract:
```rust
use operad::core::{UiDocument, UiNode, UiPoint, UiRect, UiSize};
use operad::widgets::{button, checkbox, slider};
```
Renderer, platform, and adapter-specific code should import from the explicit
module that owns the integration:
```rust
use operad::render::{PaintItem, PaintKind, RenderFrameRequest};
use operad::adapters::wgpu;
```
## Baseline From 6.1
The v7 branch starts from the published `6.1.0` WGPU baseline:
- `wgpu` is `29.0.3`.
- `glyphon` is `0.11.0`.
- Native-window and GPU canvas consumers should not need to downgrade WGPU from
newer downstream renderers just to adopt v7 work.
## Source Layout Changes
The first v7 structure pass moved the retained document implementation out of
`src/lib.rs` into `src/core/document.rs`. The crate root still re-exports these
types, so existing imports such as `operad::UiDocument` and `operad::UiNode`
continue to work.
The inline `widgets` module moved from `src/lib.rs` into `src/widgets/mod.rs`.
The public module remains `operad::widgets`.
## V7 Widget Additions
V7 adds normal widget builders for surfaces that previously required examples
or applications to hand-build low-level document nodes:
- `operad::widgets::collapsing_header`
- `operad::widgets::link`
- `operad::widgets::hyperlink`
- `operad::widgets::selectable_label`
- `operad::widgets::selectable_value`
- `operad::widgets::small_button`
- `operad::widgets::icon_button`
- `operad::widgets::image_button`
- `operad::widgets::toggle_button`
- `operad::widgets::reset_button`
- `operad::widgets::form_section`
- `operad::widgets::form_row`
- `operad::widgets::field_label`
- `operad::widgets::field_help_text`
- `operad::widgets::field_validation_message`
- `operad::widgets::form_error_summary`
- `operad::widgets::form_action_buttons`
- `operad::widgets::form_field_order`
- `operad::widgets::next_form_field`
- `operad::widgets::previous_form_field`
- `operad::widgets::central_panel`
- `operad::widgets::top_panel`
- `operad::widgets::bottom_panel`
- `operad::widgets::side_panel`
- `operad::widgets::left_panel`
- `operad::widgets::right_panel`
- `operad::widgets::area`
- `operad::widgets::scene`
- `operad::widgets::group_panel`
- `operad::widgets::frame`
- `operad::widgets::group`
- `operad::widgets::sides`
- `operad::widgets::columns`
- `operad::widgets::indented_section`
- `operad::widgets::resize_handle`
- `operad::widgets::resize_container`
- `operad::widgets::compact_color_button`
- `operad::widgets::color_swatch_button`
- `operad::widgets::color_edit_button_rgb`
- `operad::widgets::color_edit_button_rgba`
- `operad::widgets::color_edit_button_rgba_premultiplied`
- `operad::widgets::color_edit_button_rgba_unmultiplied`
- `operad::widgets::color_edit_button_srgb`
- `operad::widgets::color_edit_button_srgba`
- `operad::widgets::color_edit_button_srgba_premultiplied`
- `operad::widgets::color_edit_button_srgba_unmultiplied`
- `operad::widgets::color_picker_color32`
- `operad::widgets::color_picker_hsva_2d`
- `operad::widgets::color_edit_button_hsva`
- `operad::widgets::color_edit_button_oklch`
- `operad::widgets::show_color`
- `operad::widgets::show_color_at`
- `operad::widgets::menu_button`
- `operad::widgets::image_menu_button`
- `operad::widgets::image_text_menu_button`
- `operad::widgets::submenu`
- `operad::widgets::submenu_button`
- `operad::widgets::singleline_text_input`
- `operad::widgets::multiline_text_input`
- `operad::widgets::text_area`
- `operad::widgets::code_editor`
- `operad::widgets::search_input`
- `operad::widgets::password_input`
- `operad::widgets::tooltip_box`
- `operad::widgets::tooltip_trigger_resolution`
- `operad::widgets::tooltip_fade_slide_animation`
- `operad::widgets::modal_dialog`
- `operad::widgets::modal_dialog_descriptor`
- `operad::widgets::modal_dialog_focus_trap`
- `operad::widgets::modal_dialog_open_event`
- `operad::widgets::modal_dialog_dismiss_event_from_input_result`
- `operad::widgets::modal_dialog_dismiss_event_from_pointer_event`
- `operad::widgets::modal_dialog_dismiss_event_from_key_event`
- `operad::widgets::dnd_drag_source`
- `operad::widgets::dnd_drop_zone`
- `operad::widgets::dnd_drag_source_descriptor`
- `operad::widgets::dnd_drop_target_descriptor`
- `operad::widgets::dnd_drag_start_request`
- `operad::widgets::dnd_drop_zone_preview_state`
- `operad::widgets::dnd_apply_drop_zone_preview`
- `operad::widgets::scroll_area_with_bars`
- `operad::widgets::aligned_scrollbar_options`
- `operad::required_pipeline_stages`
- `operad::required_cache_diagnostic_kinds`
- `operad::widgets::drag_angle`
- `operad::widgets::drag_angle_tau`
- `operad::widgets::add_visible`
- `operad::widgets::add_visible_ui`
- `operad::widgets::add_enabled`
- `operad::widgets::add_enabled_ui`
- `operad::widgets::add_sized`
- `operad::widgets::allocate_exact_size`
- `operad::widgets::allocate_at_least`
- `operad::widgets::allocate_painter`
- `operad::widgets::scroll_to_cursor`
- `operad::widgets::scroll_to_rect`
- `operad::widgets::scroll_to_rect_with_options`
- `operad::widgets::theme_preference_buttons`
- `operad::widgets::theme_preference_switch`
`selectable_label` is a selectable/toggleable label control. It is intentionally
separate from `selectable_text`, which remains a read-only text input variant
for copy and text-selection behavior. `selectable_value` is a thin helper that
marks a label selected when an application-owned value equals the option value.
The button convenience builders share `ButtonOptions` with `button`. They are
thin defaults for common cases rather than separate state models.
`drag_angle` and `drag_angle_tau` share `DragValueOptions` with
`drag_value_input`; they only provide degree and tau-fraction formatting
defaults.
The visible/enabled, allocation, painter, and programmatic scroll helpers are
widget-adjacent convenience APIs. They wrap retained document primitives without
changing ownership: applications still own whether content is shown, enabled, or
scrolled into view.
`theme_preference_buttons` and `theme_preference_switch` are normal widget
builders for exposing application-owned theme preferences. They emit widget
actions; applications still own resolving System, Light, and Dark choices into a
theme.
`tooltip_trigger_resolution` maps hover/focus input state into `TooltipRequest`
values using `HelpTimingPolicy`. `tooltip_fade_slide_animation` provides the
default tooltip animation preset and accepts a reduced-motion flag.
`modal_dialog` now carries dismissal policy, focus-trap preferences, and
focus-restore defaults in `ModalDialogOptions`. The modal helper functions map
the visual dialog nodes into `DialogDescriptor`, `FocusTrap`, and
`OverlayFrameEvent` values so examples and applications do not need to hand-wire
normal open, Escape, outside-click, or close-button behavior.
`DragSourceOptions` now includes a `DragImagePolicy`, and platform
`DragDropRequest::Start` carries optional `DragImage` metadata for adapters that
support custom drag images. `dnd_drop_zone_preview_state` and
`dnd_apply_drop_zone_preview` provide the standard accepted, rejected, hovered,
disabled, and idle drop-preview behavior.
`scroll_area_with_bars` builds a scroll viewport plus optional vertical and
horizontal scrollbar nodes from one `ScrollState`. `aligned_scrollbar_options`
keeps standalone scrollbar tracks sized to the scroll viewport so custom
scrollable widgets do not need per-widget alignment code.
`PerformanceSnapshot` now reports both required frame pipeline stages and
required cache diagnostic domains. Use `required_pipeline_stages`,
`required_cache_diagnostic_kinds`, and `DiagnosticReport::performance_snapshot`
when building local stress probes or explaining a slow frame.
The form helpers build visual form rows, labels, help text, validation messages,
summaries, and action rows around `FormState`, `FieldState`, and
`ValidationMessage`. Applications still own field values and the effects of
submit/apply/cancel/reset actions.
The container and panel helpers are convenience builders over the retained
document tree. Existing `panel` and `UiNode::container` code keeps working, but
new examples should prefer the named helpers when building ordinary panels,
frames, absolute areas, scene primitive blocks, side-by-side sections, columns,
indentation, or resizable regions.
The color button helpers use the existing color picker state and action model.
They are compact trigger/display widgets for common color formats; applications
still decide whether a click opens a picker, copies a value, or commits a
color change. The premultiplied variants display an unpremultiplied swatch
while preserving the stored premultiplied channel values in the accessible
value text.
The menu-button helpers use `MenuButtonState`, `MenuItem`, and anchored popup
geometry from the previous layout pass. They compose normal menu-list popups
and anchored submenus without requiring examples to hand-build menu rows or
inline popup panels.
The text-input convenience builders all use `TextInputState` and
`TextInputOptions`; they configure common defaults without replacing the
existing state/event handling model. `password_input` masks only the rendered
document state. Applications should keep owning the real text state.
The existing tooltip, dialog, and overlay contracts remain available for state,
timing, dismissal, and focus policy. The new surface builders are the preferred
way to create the visual document nodes.
The drag/drop builders use the existing `DragPayload`, `DragOperation`,
`DragSourceDescriptor`, and `DropTargetDescriptor` contracts. Build the visual
surface with the widget helper, then derive the descriptor from the rendered
node when platform drag/drop routing needs bounds.
## Current Public Path Status
| `operad::UiDocument` | Kept | Common root export. |
| `operad::UiNode` | Kept | Common root export. |
| `operad::UiPoint`, `operad::UiRect`, `operad::UiSize` | Kept | Common geometry exports. |
| `operad::widgets::*` | Kept | Preferred widget module. |
| `operad::prelude::*` | Added | Preferred broad app import. |
| `operad::core::document::*` | Added | Owns retained document primitives. |
| `operad::layout` | Kept for v7 | Common layout helpers remain root-level because existing examples and consumers use them heavily. Prefer `operad::core::layout` once that module path is introduced. |
| `operad::input`, `operad::actions`, `operad::commands`, `operad::navigation`, `operad::overlays`, `operad::transactions` | Kept for v7 | These remain root modules and are also grouped under `operad::interaction`. New docs should prefer the grouped path for interaction concepts. |
| `operad::paint`, `operad::renderer`, `operad::display`, `operad::resource_cache`, `operad::scrolling`, `operad::virtualization` | Kept for v7 | These remain root modules and are also grouped under `operad::render`. New docs should prefer the grouped path for rendering concepts. |
| `operad::host`, `operad::platform`, `operad::runtime`, `operad::windows` | Kept for v7 | Runtime contracts remain available at their v6 paths while `operad::runtime` becomes the preferred grouping. |
| `operad::wgpu_renderer` | Kept for v7 | Feature-gated compatibility module. New WGPU docs should prefer `operad::adapters::wgpu` once that adapter path is added. |
| `operad::egui_host` | Kept for v7 | Feature-gated compatibility module. New egui docs should prefer `operad::adapters::egui` once that adapter path is added. |
| `operad::accesskit_winit_adapter` | Kept for v7 | Feature-gated compatibility module. New accessibility adapter docs should prefer the adapter grouping once it is added. |
| Root type re-exports, for example `operad::PaintItem`, `operad::WidgetAction`, and `operad::RenderFrameRequest` | Kept for v7 | Common type re-exports stay to keep examples short. Module paths should be used when a doc section is about ownership boundaries. |
No v6 public path is deprecated by the Alpha 1 structure pass. V7 can still
deprecate paths later, but each deprecation must update this guide and the
changelog in the same change.
## Current Dependency Status
| `wgpu` feature | Kept | Uses WGPU 29 through the v6.1 baseline. |
| `glyphon` through `wgpu` | Kept | Uses Glyphon 0.11, which depends on WGPU 29. |
| `native-window` feature | Kept | Continues to depend on WGPU, winit, and clipboard integration. |
| no-default builds | Required | Must not pull WGPU, winit, glyphon, egui, AccessKit, or clipboard crates. |
## Migration Checklist For V7 Work
When a v7 change moves or renames a public item:
1. Update this guide in the same change.
2. Keep or remove the root export intentionally.
3. Add a short compatibility note to the changelog draft.
4. Update examples to use the preferred path.
5. Run no-default and all-features checks that cover the affected feature gates.
## Not Yet Decided
- Whether old internal planning documents should be packaged in crates.io
releases or moved under an archive folder before v7.