Crate teksilo_scene

Expand description

teksilo-scene — pannable / zoomable scene viewport for Teksilo.

A sub-toolkit for scene-based applications — story corkboards, mind maps, node-graph editors, timeline views — where content is free-positioned at scene coordinates instead of placed by a layout algorithm. Two tiers of content coexist under one view transform:

Heavyweight tier: any Widget (Button, TextInput, Panel, composite components) at a parent-relative position, fully interactive and accessible, with full event / focus / animation / a11y machinery intact.
Lightweight tier: SceneItems (paths, rects, images, custom paint) without arena overhead — for the “background furniture” of a scene where thousands of items render cheaply.

The crate is built on top of teksilo-core’s per-node set_transform scope (which composes through hit-test, paint, and a11y) and the platform’s pinch / scroll / animated-Signal<f32> infrastructure — so OS gestures, reduced-motion snapping, and the four-gate idle scheduler fall out for free.

See docs/teksilo-scene.md for the user-facing reference and docs/teksilo-scene-a11y.md for the accessibility-shaping API.

§Quick start

use teksilo_scene::{ItemId, RectItem, Scene, SceneView};
use teksilo_canvas::{Point, Rect};

let mut scene = Scene::new();
let _w: ItemId = scene.add_widget(
    my_card_widget(),
    Rect::new(0.0, 0.0, 200.0, 120.0),
);
scene.add_item(
    RectItem::new(Rect::new(0.0, 0.0, 50.0, 50.0)).fill(teksilo_tokens::Color::RED),
    Point::new(220.0, 0.0),
);
let view = SceneView::new(scene);
tree.add(view);

Structs§

A11yCategory: App-defined category tag for AT rotor / quick-nav navigation. Surfaced to AT clients that support categorized navigation (VoiceOver rotor on macOS, NVDA quick-nav). Apps coin their own tag values like "node", "connector", "comment".
A11yGroup: A logical AT group. Pure structure — no visual counterpart, no hit-test, no paint. Declares AT-shape that diverges from visual scene layout (Acts containing Scene cards, Subgraphs containing Nodes, Layers containing Components).
A11yGroupBuilder: Builder for an A11yGroup. Returned by A11yGroup::builder; consumed by Scene::add_a11y_group.
A11yGroupId: Opaque identifier for a logical AT group declared via Scene::add_a11y_group. Stable across the lifetime of the process; safe to hash, compare, store.
CascadeBudget: The runaway-detection budget for one scene’s change fan-out — how much work observers may generate from one batch before the drain declares the cascade non-terminating and panics.
DebugOverlay: Visual debug overlays painted on top of normal scene rendering.
GridHashIndex: Uniform grid spatial hash. Each item is bucketed into every cell its AABB overlaps; queries union all items from the cells the query rect overlaps. Items whose AABB would span more than MAX_CELLS_PER_ITEM cells are NOT bucketed — see oversized below and the module doc’s “Oversized items” section.
GroupItem: A group container with optional fill / stroke / inline label, in local item coordinates.
HandlerReplacement: The two sides of a Scene::set_item_handlers, as they ride an ItemChange::HandlersChanged.
ImageItem: A raster image in a local-coord rectangle.
ItemA11yDecorations: The per-item slice of the logical accessibility tree, harvested by Scene::take and re-attached by Scene::restore.
ItemFlags: A bitset of per-item behavior flags.
ItemId: Opaque identifier for a SceneItem inside a Scene.
ItemPayload: A Delegated heavyweight entry’s type-erased payload, as it rides an ItemChange::PayloadChanged.
ItemShape: What an item’s geometry is, in local item coordinates — the single source of truth for hit-test, marquee, collision and path queries.
Magnet: A magnetism anchor attached to a scene item.
MagnetConnection: A formed connection between two magnets, delivered to the consumer’s on_connect handler on release (mouse) or confirm (keyboard).
MagnetFeedback: Everything the magnetism feedback renderer needs for one frame, in scene coordinates (the canvas is already in the view-transform scope). The built-in renderer draws markers plus a connector; a custom MagnetismConfig::feedback closure receives the same data.
MagnetId: Opaque identifier for a Magnet inside a Scene.
MagnetMarker: One magnet’s render data, handed to the feedback renderer.
MagnetRef: An owned, borrow-free snapshot of one magnet, handed to the accept/reject predicate and carried in a MagnetConnection.
MagnetSnap: The chosen snap when a dragged item’s magnet aligns onto another item’s magnet. Returned by Scene::compute_item_snap.
MagnetismConfig: Per-view magnetism configuration, installed via SceneView::magnetism.
MinimapReadout: Where the viewport sits inside the picture the minimap is drawing — the numbers behind the AT node’s announced value, as plain fractions.
PaintKey: Where an entry sits in a SceneView’s single paint order.
PathItem: An arbitrary vector path with optional fill and stroke, in local item coordinates.
Placement: Where an item sits, as one property: logical parent, paint z, position in the parent frame, and local to parent transform.
ProposedChange: A change a gesture is about to make, offered to the geometry constraint.
RectItem: A rectangle with optional fill and stroke, in local item coordinates.
RemovedItem: One item lifted whole out of a Scene: its entry, its magnets and its logical-AT decorations, still owned and still carrying its original ItemId.
ReplaceRejected: A refused Scene::replace_item: why, and the item it did not take.
Scene: The data model behind a SceneView: a flat list of entries in a parent-relative scene-graph plus a SpatialIndex for rectangular queries.
SceneCard: A heavyweight scene item’s container: surface, header, body, modes, gestures and accessibility. See the scene_card module docs.
SceneChange: One ItemChange plus the context the notification channel needs in order to be usable as a change feed rather than just a repaint trigger.
SceneConstraints: Reactive interaction-policy bundle owned by Scene. Apps configure pan/zoom behaviour by writing to these signals; gesture closures in SceneView read them live, so runtime mode switches (e.g. a toolbar toggling pan locks) take effect on the next event without rebuilding the view.
SceneItemA11yContext: Context handed to SceneItem::accessibility.
SceneItemHandlerSet: Per-item event closures + cursor + tooltip + drop acceptance.
SceneItemPaintContext: Context handed to SceneItem::paint.
SceneListAdapter: Keeps a set of lightweight SceneItems in sync with a teksilo_data::ListModel<T> / ListDataSource<Item = T>.
SceneMinimap: A small thumbnail rendering of a Scene’s content, with the live viewport rectangle highlighted.
SceneModel: A shared, cloneable handle to a Scene.
SceneRegion: The region a geometry query asks about.
SceneScrollView: A SceneView with draggable scroll bars.
SceneSelection: Reactive selection state for a Scene.
SceneTapEvent: Click-style gesture envelope for scene items. Mirrors the widget-tier [teksilo_core::gesture::TapEvent] but with the position in scene coordinates instead of widget-local. Used by the tap / double-tap / triple-tap / long-press / context-menu handlers on SceneItemHandlerSet.
SceneTransaction: An open transaction over a SceneModel: every edit until it drops is one logical change.
SceneTransactionRecord: One committed transaction, delivered to the edit sink with the scene unborrowed.
SceneView: A pannable/zoomable viewport that renders a Scene’s items at scene coordinates and routes user input (scroll, pinch, drag, keyboard) back into the camera signals.
SceneViewState: Snapshot of a SceneView’s view transform: pan offset, zoom factor, and rotation in radians. Use SceneView::state to capture the current values; SceneView::restore_state to apply a saved snapshot.
SceneWriteGuard: Write guard over a SceneModel’s Scene: Deref/DerefMut to the scene, with the deferred-notification contract of a SceneModel mutator.
ShapeGeometry: A [Path] plus its flattening, computed once and shared by handle.
TextItem: Text in a local-coord rectangle, with optional alignment and rotation.
TransformChrome: Everything the chrome painter is told. Scene coordinates throughout — the view transform is already on the canvas, exactly as for MagnetismConfig::feedback.
TransformConfig: Per-view transform-controller configuration, installed via SceneView::transform_controller.
TransformDelta: What one in-flight gesture asks of the selection, stated once in scene coordinates.
TransformFrame: The box the handles are drawn on.
TransformHandleSet: A bitset of TransformHandles — Konva’s enabledAnchors, in the house style of ItemFlags.
TransformLabels: The assistive-technology names the controller publishes.
TransformSession: A snapshot of the live session, handed to the three event hooks and published by SceneView::transform_session_signal.
TxnId: Process-unique id for one transaction.
WeakSceneModel: A non-owning handle to a Scene — SceneModel without the ownership.
WetLayer: A surface for content being authored right now, which repaints without taking the scene’s item bands with it.
WetNode: One of a WetLayer’s mounted paint nodes, as WetLayer::nodes reports it.

Enums§

A11yMode: AT-emission strategy for SceneView. Decides whether items / widgets that have not been placed in the app-declared logical tree appear in the AT tree by default, or are suppressed.
A11yNode: Address of a node in the parallel logical AT tree. Lets apps uniformly target scene entries, virtual groups, and ad-hoc widgets when declaring relationships, parents, or rotor categories.
A11yOffScreenMode: Off-screen visibility policy for the AT walker. Decides which scene items get emitted as synthetic AT nodes per AT-rebuild.
A11yRelation: AT relationship kind, applied via Scene::add_a11y_relation. Maps to AccessKit’s relationship arrays.
AccessSubtreeMode: How the AT walker treats descendants of an item.
AppearanceChange: Which paint-only appearance slot changed, with both sides of the write.
AppearanceWrite: What a SceneItem appearance setter did — and, when it did anything, the value it overwrote.
CacheMode: Per-item paint caching strategy.
CardMode: What a SceneCard is doing.
ChangeSource: Whose change this is.
ChangeVerdict: What a geometry constraint decides.
DragMode: What a SceneView’s on-canvas pointer drag does in empty space.
FocusDirection: Direction passed to a SceneView::focus_order callback when the app wants to override the default Tab cycle.
HistoryMode: What a history above the scene should do with this transaction.
ItemChange: A change to an item’s state, fired through Scene::item_change_signal for every mutation. Apps observe to wire validation, persistence, telemetry, mirroring to a data layer, and other side effects. The model is “fire after the change has been applied” — by the time the observer sees the event, the Scene already reflects it, and (when the mutation came through a SceneModel) the observer may freely read and write the scene back.
ItemSelectionMode: How a region query decides whether an item is picked — Qt’s Qt::ItemSelectionMode, one variant for one.
LivePreview: Whether the items follow the gesture or only the frame does.
MagnetRole: The direction a magnet faces in a connection.
MagnetVerdict: The result of running the accept/reject predicate on a candidate magnet pair. “Both payloads in, reject or accept-with-payload out.”
MagnetVisualState: The visual state of a magnet as the feedback renderer sees it.
MarkerVisibility: When the SceneView paints magnet markers.
PanAxes: Which axes a SceneView is allowed to pan along. Set on the Scene (not the View) because a given scene model often makes sense at one orientation only — a horizontal timeline, a vertical timeline, a fixed-extent diagram. All views of the same scene inherit the constraint.
ReplaceItemError: Why Scene::replace_item could not swap an item box. Travels inside a ReplaceRejected, which also carries the item.
RestoreError: Why Scene::restore could not put a salvage back.
Salvage: The ownership an ItemChange cannot carry, attached to the removal that produced it.
SceneEdit: One edit inside a SceneTransactionRecord, in application order.
SceneLayer: Which paint band a lightweight SceneItem sits in, relative to the heavyweight widget tier.
SceneSelectionMode: Selection-mode discriminator. Mirrors teksilo_data::SelectionMode.
ScrollBarMode: How the scroll bar is presented relative to the viewport content.
ScrollBarPolicy: Controls when the scroll bar appears for a given axis.
SizePolicy: How an entry’s local_bounds is decided each layout pass.
TextAlign: Horizontal alignment of a TextItem within its local_bounds.
TransformHandle: One grab affordance on the selection frame.
TransformOp: What one gesture asks of the selection.
TransformOutcome: How a session finished.
TransformSource: Which route produced a session.
TransformStep: One directional nudge on a transform handle.
TxnOutcome: How a transaction finished.

Constants§

DEFAULT_EDGE_PAN_PX: Default distance from the viewport edge at which a pointer gesture starts panning the view, in screen pixels.
DEFAULT_EDGE_PAN_SPEED: Default auto-pan speed, in screen pixels per second.
DEFAULT_HANDLE_PX: Default handle size, in screen pixels.
DEFAULT_PADDING_PX: Default frame padding, in screen pixels. Chosen so the handle discs clear the selection’s own bounds: a card never owns the pixels a handle is drawn on, which is what makes the chrome grabbable over a heavyweight child.
DEFAULT_RETENTION_MARGIN: Default SceneView::retention_margin, in screen pixels.
HIT_BAND_SLACK: Grab tolerance added to every stroke band’s half-width, in local coordinates.
RANK_OVER: The PaintKey::rank of a lightweight item in the Over band.
RANK_UNDER: The PaintKey::rank of a lightweight item in the Under band.
RANK_WIDGET: The PaintKey::rank of a heavyweight widget entry.
ROTATE_OFFSET_PX: How far above the frame the rotate puck floats, in screen pixels.
SHAPE_FLATTEN_TOLERANCE: Curve-flattening tolerance, in local item coordinates.

Traits§

SceneItem: A lightweight, paint-only scene-graph item.
SpatialIndex: A spatial index over ItemIds keyed by axis-aligned scene rectangles. Used by Scene for items_in_rect queries and by SceneView for viewport culling.

Functions§

claims_press: Whether an entry would act on a press — the occlusion rule of this module, in one predicate.
hit_testable: Whether an entry takes part in pointer hit-testing at all.
pulse_once: One-shot ease-out tween from the signal’s current value to target over duration. The standard “fire on click, dismiss” / “flash a highlight” pattern. The signal must already be registered with register_animated_item_signal (or directly via ctx.register_animated_signal) for the tween to participate in idle gating.
register_animated_item_signal: Register an item-owned Signal<f32> with the SceneView’s animation scheduler. Call this from inside SceneItem::register_bindings for every animated signal the item exposes.