* claim: #11305 * Panels: add columns, stacks and tabs with exact drag previews (#11305)
292 lines
19 KiB
Markdown
292 lines
19 KiB
Markdown
# Universal panel foundation
|
|
|
|
The public contracts are `solidcraft_engine::panels` and
|
|
`solidcraft_ui_egui::panel_runtime`. The #11305 host is explicitly enabled and
|
|
uses synthetic controllers to exercise shared behaviour. Production Browser,
|
|
History, Assistant, Render, Sketch, feature forms and BOM adapters are sibling
|
|
work. The shipping shell, content, preferences and Classic behaviour retain
|
|
their existing defaults. A specimen is not production migration or visual evidence.
|
|
The current migration boundary permits only existing docked Browser, History and
|
|
Assistant content and their allowed Render counterparts in future sibling work.
|
|
Draggable tool windows and the existing native Assistant retain their legacy hosts.
|
|
|
|
## Ownership
|
|
|
|
The engine registry owns bounded kind metadata and capabilities. Layout owns
|
|
instance, column, section and tab identities, placement memory, widths, saved
|
|
weights, collapse, active tabs and native return destinations. Side columns are
|
|
ordered outer to inner; each contains a contiguous vertical stack of sections.
|
|
Each section contains ordered tabs. Inactive tabs still constrain composite size
|
|
limits. Registrations declare allowed zones, PinOuter, Content/Fill height policy,
|
|
text-heavy content, surface preference, header actions and independent
|
|
`closable`/`hot_closable` flags. No generic host branches on product panel names.
|
|
Only future History product registration allows Bottom; synthetic kinds can allow
|
|
all zones. Quick close is an affordance, not the close capability itself.
|
|
|
|
Layout is application/workspace preference data. It never enters CAD files,
|
|
document undo, evaluation or tessellation. `PanelRuntime` retains controllers by
|
|
instance and `ContentOwner`, independent of presentation. Services tick while
|
|
controllers are collapsed, inactive, unavailable, closed or on inactive documents.
|
|
Owner changes retain the appropriate draft/controller rather than redirecting an
|
|
old document's model reads to a new document. Explicit close/destroy/reopen and
|
|
reparent have side-effect-free lifecycle preflight before commit. Hidden bodies
|
|
are not rendered to measure them or animate collapse.
|
|
|
|
`PanelModels` reads immutable owner models. Explicit content operations use
|
|
`ContentCommandSink`. `PanelLocalServices` owns viewport-local keyboard, focus,
|
|
clipboard, picking, drops and overlays. Registered header actions must also have a
|
|
retained controller binding and pass availability/enabled checks. `panel.action`
|
|
returns a truthful committed `LayoutReply`; it cannot invoke an unregistered
|
|
binding. A fallible content action cannot be mixed with structural mutations in
|
|
one runtime transaction. Synthetic Apply/Finish/Pulse actions never run Session
|
|
commands. Real History playback and Assistant New Chat bindings belong to their
|
|
content migrations.
|
|
|
|
## Allocation and presentation
|
|
|
|
The pure engine allocator is authoritative for both commands and gestures. It
|
|
intersects every tab's constraints and each column's width constraints, uses
|
|
constrained saved weights for stacks, and preserves minimum dimensions when the
|
|
window is tiny. Right and Bottom placement share a bounded scroll extent, avoiding
|
|
overlapping docked hosts. The viewport domain stays fixed below the application
|
|
bar, including behind the ribbon and panels.
|
|
|
|
A sole presented side section defaults to Content height. The active tab supplies
|
|
bounded preferred outer height at the assigned width, including shared header,
|
|
body, content toolbar, footer, padding and spacing. Fill consumes available height
|
|
within the same composite limits. Multiple sections use their saved stack weights;
|
|
entering/leaving the sole-section state does not rewrite them. Collapse reserves
|
|
only the full-width header and leaves genuine uncovered canvas below short or
|
|
all-collapsed stacks.
|
|
|
|
Expanded dock sizing can declare `preferred_extent` on the stack axis. An
|
|
omitted preference remains None; saved legacy size does not imply a new override.
|
|
After reserving every presented minimum, allocation processes `extent_priority`
|
|
tiers highest-first, compressing requested surplus proportionally within a tier
|
|
when necessary. Older/common preferences use rank 0; nonexplicit members receive
|
|
the weighted remainder. SetSize authors a new highest tier. Ordinary weighted
|
|
pair resize/reset clears the pair's overrides/ranks; when weights cannot represent
|
|
a feasible actual split, the pair's exact requested extents receive one new tied
|
|
highest tier. Repeated overlapping edits therefore favor the latest authored pair
|
|
under later compression while preserving older preferences. Unrelated neighbours
|
|
keep their rectangles, even when their normalized weights need a common scale;
|
|
zero saved surplus remains valid. Sole side Content/Fill ignores latent extent
|
|
and rank during presentation and retains them for returning to a stack.
|
|
|
|
Bottom top-edge dragging uses the typed `SetBottomHeight` mutation. Registered
|
|
`panel.resize` with `thickness_only:true` uses the same mutation for Bottom, or
|
|
`SetColumnWidth` for a side dock; Floating/Window refuse. Omitted/false retains
|
|
full-size behavior. Both size components are validated before ignoring the other
|
|
axis. `SetBottomHeight` changes shared row thickness within registered common
|
|
bounds while preserving every Bottom width, preferred width, rank and weight. There is no additional public
|
|
string command. The side/Bottom separator exists only when side geometry presents;
|
|
a Bottom-only 64-point row fits exactly in 64 points of capacity.
|
|
|
|
`PanelController::measure(&self, owner, models, spec)` captures an immutable
|
|
`Arc<dyn HostContentMetrics>` snapshot. Its bounded `measure(request)` answers
|
|
assigned-width requests without a renderer or mutable services. `revision()` must
|
|
change whenever any answer could change, including responsive policy. The default
|
|
reports registered preferred outer height explicitly; it does not claim intrinsic
|
|
content measurement. Adapters supply real bounded metrics. `host_measure_requests`
|
|
uses the same width allocator as resolution; candidate widths are measured before
|
|
a preview is shown. Missing/stale data rejects. Replacing metric data cancels the
|
|
old candidate. The host retains the same snapshot identity while its revision is
|
|
unchanged, avoiding geometry feedback from an already stretched parent.
|
|
|
|
`HostLayout` separates intended section slots, scroll extent, actual clipped
|
|
paint/input/occlusion footprints and usable-space contour. `ResolvedPanel.body`
|
|
and `PanelContext.usable_body` are optional. Collapsed hosts have no content body.
|
|
Expanded Wide geometry at or below `theme::PANEL_INLINE_MAX_HEIGHT` (88 logical
|
|
points) has one total row: the real shared title/grip, registered actions, dedicated
|
|
inline content, menu, chevron and optional quick close, fully mirrored in RTL. It calls
|
|
`render_inline`, whose compatibility default delegates to Body. It does not call
|
|
Header/Body/Footer again or add a second title band. Controllers can override the
|
|
inline slot with a compact representation. This generic capability is demonstrated
|
|
by an editable inline specimen, not a substitute History timeline.
|
|
|
|
Shared chrome uses the existing adaptive `ui_kit::Container`, panel fill, title
|
|
fonts, six-dot grip and header separator. Each section has one header row. A single
|
|
panel uses a text-only title and grip; a tab group uses one leading section grip
|
|
and individual text-only tab headings in that same row, with no duplicate active
|
|
title. Grip, tabs and controls have disjoint hitboxes at the same y and height.
|
|
The grip drags the active tab; each tab retains its own select, drag and reorder
|
|
target. Header title typography is independent of icon metadata, which remains
|
|
available to other presentations. Collapsed groups retain their tabs across the
|
|
full-width header. Inline groups use their allocated title region for grip/tabs,
|
|
preserving the actual inline editor and one total row. Compact tab overflow keeps
|
|
the active heading visible whenever its minimum width fits beside the overflow
|
|
button; the bounded accessible menu retains every tab. Measurements and allocation
|
|
count only the shared header, content toolbar and footer, with no extra tab-row
|
|
height. Floating shell spacing comes from
|
|
`Container::gap()` and participates in allocation, previews and input geometry;
|
|
compact surfaces join without a sizing gap. In LTR, the
|
|
trailing controls are custom actions, menu, chevron, optional quick close; RTL
|
|
mirrors their geometry. Collapse retains these controls and one click on its
|
|
chevron restores the body. There is no rail, hover-peek or pin-open product UI.
|
|
Published `panel.peek`/`panel.dismiss` compatibility commands retain their wire
|
|
meaning without creating a new host affordance.
|
|
|
|
Overflow retains actual panels at minimum dimensions. Narrow scroll tracks and
|
|
unconsumed wheel input over actual panel paint change presentation offset. The
|
|
scroll canvas itself has no full-viewport response; uncovered gaps stay navigable.
|
|
Content retains its own scroll area and gets first use of wheel input.
|
|
|
|
## Exact candidates and admission
|
|
|
|
`prepare_host_layout` produces a non-Clone `PreparedHostLayout` containing private
|
|
engine state, proposed geometry, reference geometry and scope. Both app commands
|
|
and pointer actions use this preparation and allocator. Missing host/environment
|
|
refuses structural app commands. `NO_SPACE` refuses neutral or worsening overflow
|
|
except Close, Collapse (including expansion), Focus, or a strict improvement of one
|
|
extent without increasing the other.
|
|
|
|
Drags start after six logical points. Invisible card-edge regions select adjacent
|
|
columns or stacked sections; the centre joins tabs and measured tab halves choose
|
|
insertion. Side ordering accounts for both dock side and RTL. Empty space has no
|
|
implicit float fallback. Floating is an explicit menu/command action.
|
|
|
|
Once a Move crosses that threshold, the current moved instance's full presentation
|
|
title follows the cursor on the existing preview paint layer, including over
|
|
invalid or absent landing targets. Its original header or tab title uses half
|
|
its existing ink opacity; other text, grips, actions and panel content keep their
|
|
normal appearance. The paint-only badge uses theme tokens, mirrors its cursor
|
|
offset in RTL and clamps within the render domain and current clip. It keeps
|
|
the full display-ordered title on one line without automatic wrapping or
|
|
ellipsis. Physically oversized text clips, aligned left in LTR and right in RTL
|
|
so its reading start stays visible. It adds no widget, input, occlusion or
|
|
usable-space reservation. Mere presses,
|
|
clicks, resize and paired-resize gestures have no title feedback.
|
|
|
|
Window docking takes priority over panel targets: Bottom first, then sides,
|
|
measured tab insertion, relative edges and centre joins. Side bands are 16 logical
|
|
points wide (56 on empty sides); the Bottom band is 64 points high. Only the
|
|
innermost presented receiving column's centre-facing edge reaches 64 points into
|
|
clear canvas. Other outward column edges retain 18 points. Added reach stops at
|
|
painted panels or chrome and preserves the original edge-band tie-breaking.
|
|
|
|
The Below region extends through clear column space under a short panel, stopping
|
|
at the next visible panel, chrome or placement boundary. It adds no idle widget
|
|
or canvas obstacle. New stacked sections use the anchor's relative weight scale;
|
|
logical pixel heights do not become weights against normalized proportions.
|
|
|
|
Only the selected successful candidate's complete landing, changed neighbours
|
|
and tab marker are painted. Targets are data, never idle widgets. Preview does
|
|
not mutate committed layout, preferences, controllers, identities, document or
|
|
camera. Release consumes the unchanged shown candidate once. It does not rerun
|
|
an action reconstructed from the preview. Runtime performs lifecycle, action and
|
|
native preflight before committing that same prepared engine state. Resize uses
|
|
the same ownership protocol. Invalid/outside release, Escape, cancellation,
|
|
focus/visibility/modal loss, independent commands, changed scope, revision,
|
|
availability, metrics or environment discard capture without mutation.
|
|
Pointer leave hides the preview and discards its candidate while retaining a
|
|
valid held gesture. Re-entry resolves a fresh candidate. A button released
|
|
outside cannot resume a drag on re-entry; actual focus loss still cancels it.
|
|
The held Move's source text stays dim during pointer absence, but its badge has
|
|
no position and is hidden until a fresh inside Move. Cancellation or release
|
|
removes the badge and requests a repaint to restore the already-painted source
|
|
text. These visual observations derive from capture, never from `HostPreview`
|
|
or a second gesture state.
|
|
|
|
The runtime owns one private proposal containing B's prepared host layout and
|
|
one staged incoming controller cohort. B captures once from a pure owner/topology
|
|
projection before numeric pair normalization. Controller construction does not
|
|
use temporary placement dimensions. Every numeric prefix and final admission use
|
|
that same availability/provider snapshot; lifecycle preflight and commit reuse
|
|
those exact objects. An explicit Open/Move can change the stack before a pair,
|
|
and a newly available floating owner need not match outgoing membership.
|
|
Availability freshness compares the captured proposed cohort, including unavailable
|
|
or unbound dormant instances, with fresh read-only answers from the same objects.
|
|
Mounting, activation and registered actions share active-or-first-available
|
|
selection while preserving remembered activation. Existing controllers are retained.
|
|
|
|
`commands::execute_layout_action` stages the app's injected catalogue before
|
|
consuming the candidate once. Its retained-candidate sink returns the exact proposed
|
|
layout during projection and never replays a reducer on pointer release. Current
|
|
full-envelope preparation context is captured through `current_envelope_snapshot`
|
|
and `host_identity_reservations` before generators run. It includes dormant/native/
|
|
quarantine identities, effective recovery priority records and completeness.
|
|
`ActionSink::project_in_context` and `dispatch_in_context` forward this full context;
|
|
a retained proposal refuses any supplied-context mismatch without replay. Incoming
|
|
workspace preparation context is retained separately from outgoing paint freshness.
|
|
Bare host defaults remain incomplete; admission fixtures read a complete synthetic
|
|
envelope rather than claiming empty recovery metadata is authoritative. The engine
|
|
command staging boundary must compare the current catalogue's full source context
|
|
again after fallible storage preparation, even when service revision is unchanged;
|
|
a differing context refuses publication of the retained proposal.
|
|
Standalone registered HeaderAction is an owner command without placement/storage
|
|
dependency; mixed structural transactions refuse. Preset/workspace replacement
|
|
uses the existing command executor with its complete incoming envelope.
|
|
|
|
Changed metrics/reservations discard pending widget intents, cached proposals,
|
|
drag and the old painted frame. Widget admission requires fresh paint. Independent
|
|
commands and batches cancel capture before parsing, even if subsequently refused.
|
|
Explicit Close/Open intent remains attached when the exact candidate is consumed,
|
|
so lifecycle guards cannot disappear during conversion to prepared engine state.
|
|
|
|
## Application and surface boundaries
|
|
|
|
`SolveApp::enable_panel_runtime` installs an explicit retained runtime and
|
|
`AppPanelServices`; `enable_universal_panel_host` enables workspace composition.
|
|
Disabling the host unmounts the root cohort while keeping services alive. Whole
|
|
runtime teardown preflights every retained owner. Command, prepare, mount, paint
|
|
and finish boundaries refresh read-only Session context without an extra service
|
|
tick. Failure suspends stale presentation and remains inspectable in `last_error`.
|
|
The app exposes immutable runtime inspection; callers cannot replace its stored
|
|
native resource owner while native hosts exist.
|
|
|
|
The app paints the full-domain scene through its existing navigation path, paints
|
|
host chrome, and finalizes host input after later windows/modals. Initial presses
|
|
must belong to the actual enabled top-layer widget; exported geometry alone does
|
|
not authorize input through another window. Modal/hidden/focus loss cancels capture.
|
|
Foreign overlay raises and owner-scoped popup provenance use shared Container
|
|
services. Root and each native host mount complete separate cohorts, so unmounting
|
|
one does not deactivate another.
|
|
|
|
Panel operations never change camera, zoom, projection, focus or model screen
|
|
position. Explicit Fit uses actual usable space and may zoom. Centre/Look At
|
|
preserves zoom/distance and requested orientation, centring only focus if the
|
|
current model footprint cannot fit. Navbar/compass use their measured footprints.
|
|
Current persistent legacy forms, redefine controls, sketch palette and confirmation
|
|
paint remain obstacles after all producer passes. Sizing, closed, stale and Noop-only
|
|
hosts must not create obstacles. Transient menus shield input but do not become
|
|
framing targets. The existing semantic-content finalization and Browser editors
|
|
remain in the application shell.
|
|
The opt-in shell calls `browser::editors` once before sketch palette and
|
|
confirmation producers, retaining Move/Copy, Capture Position, Canvas, Point Cloud
|
|
and Sketch Attachment windows, drafts and command guards. Their existing shared
|
|
Window wrappers publish actual per-pass footprints; invisible sizing and closed
|
|
windows do not reserve usable space. Sketch Attachment has no second host call.
|
|
|
|
Suppressing the root Assistant clears only its cached panel, drop and dock-space
|
|
geometry, so an undrawn floating card cannot narrow legacy tool bounds. Desired
|
|
open state, conversation, backend and layout preferences remain owned by the
|
|
existing Assistant. A popped Assistant still uses `agent_chat::show` and its
|
|
existing native-window path, which performs the service poll itself; other host
|
|
composition passes call `agent_chat::poll` instead. This does not migrate or
|
|
reparent the window.
|
|
|
|
The default adapter truthfully advertises no native windows. Actual Window
|
|
placement needs the native sibling's monitor/DPI, focus and close/redock services.
|
|
The renderer retains the shared Container's fill alpha; captured `paint_alpha`
|
|
reports it separately from declarative surface intent. Input and occlusion remain
|
|
reserved regardless of alpha. Unsupported translucent effective policies still
|
|
refuse. Contrast proof, comprehensive accessibility/keyboard bindings, persisted
|
|
workspace rollout and real content adapters remain their named peers' work.
|
|
|
|
## Specimens and verification boundary
|
|
|
|
`ui.panel_fixture` is authenticated, off by default, and refuses to replace another
|
|
runtime. Presets: `docks`, `tabs`, `collapsed`, `floating`, `overflow` (24 instances),
|
|
`pinned`, `columns` (three independent Left columns), `stack_tabs`, `content_fill`
|
|
(short Content versus Fill), and `inline` (one editable total row). The old `rails`
|
|
preset is replaced by `collapsed`; it is not an alias to the retired experience.
|
|
The original synthetic controllers expose draft, transaction, action, lifecycle,
|
|
render and service counters plus process-local equality tokens. They do not expose
|
|
fake production actions or pretend to perform CAD work.
|
|
|
|
The existing engine, panel-runtime, kit, shell and viewport test files and JSON
|
|
scenarios are the locations for authored regression cases. This source describes
|
|
contracts and review fixtures; it does not claim tests, native screenshots,
|
|
performance budgets or visual acceptance have been verified. Root owns runnable
|
|
milestone builds, screenshots, user visual approval and the final checks.
|