teksilo_scene/

item.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! The [`SceneItem`] trait and its supporting context types.
//!
//! Lightweight items live in a [`Scene`](crate::Scene) without arena
//! overhead. Each carries its own bounds (in **local item coordinates**,
//! origin at the item's anchor) and paints itself via
//! [`SceneView`](crate::SceneView)'s paint walk. Apps implement this
//! trait directly for custom items; built-ins live in
//! [`crate::items`].
//!
//! # Coordinate model
//!
//! An item is positioned in its parent's coordinate space by a
//! `local_pos: Point` plus an optional `transform: Transform2D`
//! (rotation/scale, applied around the local origin). The Scene
//! composes those per-item transforms up the parent chain to produce
//! a `scene_transform` (local→scene). Hit-test inverse-transforms a
//! scene-coord point into local coords before calling
//! [`SceneItem::shape_contains`]; paint pushes the scene transform
//! onto the canvas before calling [`SceneItem::paint`].
//!
//! ## When to use
//!
//! Implement [`SceneItem`] when you need a lightweight, paint-only
//! decoration or connector that isn't interactive enough to warrant a
//! full widget (no keyboard focus, no complex event handling). For
//! anything that needs focus, animations, drag-and-drop, or AT by
//! default, prefer the heavyweight tier (`Scene::add_widget`).
//!
//! ## Custom item example
//!
//! ```ignore
//! use teksilo_scene::{SceneItem, SceneItemPaintContext};
//! use teksilo_canvas::{Canvas, Point, Rect};
//! use teksilo_tokens::Color;
//!
//! #[derive(Debug)]
//! struct DotItem { bounds: Rect }
//!
//! impl SceneItem for DotItem {
//!     fn local_bounds(&self) -> Rect { self.bounds }
//!     fn set_local_bounds(&mut self, b: Rect) { self.bounds = b; }
//!     fn paint(&self, canvas: &mut Canvas, _ctx: &SceneItemPaintContext<'_>) {
//!         canvas.fill_rect(self.bounds, Color::RED);
//!     }
//! }
//! ```

use accesskit::Role;
use teksilo_canvas::{Canvas, Point, Rect, StrokeStyle, Transform2D};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::build_context::BuildContext;
use teksilo_core::color_prop::ColorProp;
use teksilo_core::styles::Theme;
use teksilo_core::widget_id::WidgetId;

use crate::flags::ItemFlags;

/// Opaque identifier for a [`SceneItem`] inside a [`Scene`](crate::Scene).
///
/// Globally unique within a process, generated by `ItemId::next`.
/// `ItemId`s are stable across the item's lifetime in a scene; removing
/// an item retires its id permanently (`Scene::remove` does not reuse).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ItemId(pub(crate) u64);

impl ItemId {
    /// Mint a fresh globally-unique id. Used internally by Scene.
    pub(crate) fn next() -> Self {
        use std::sync::atomic::{AtomicU64, Ordering};
        static COUNTER: AtomicU64 = AtomicU64::new(1);
        Self(COUNTER.fetch_add(1, Ordering::Relaxed))
    }

    /// Raw numeric value, used by AccessKit's synthetic-NodeId derivation.
    pub fn as_u64(self) -> u64 {
        self.0
    }
}

/// Context handed to [`SceneItem::paint`].
///
/// `view_transform` is the composed pan/zoom/rotation of the SceneView
/// that's painting this item; the canvas already has the item's
/// `scene_transform` pushed, so paint methods work in local coords
/// without further matrix math.
///
/// `theme`, `window_active`, and `enabled` mirror the widget-tier
/// [`PaintContext`](teksilo_core::widget::PaintContext) so lightweight items
/// can resolve theme-aware colours exactly like widgets do — call
/// `some_color_prop.resolve(ctx.theme, ctx.enabled)` in `paint`. `theme` is
/// already the fully-projected theme for this pass (the render walker swaps in
/// the inactive-window / high-contrast variant *before* handing it here), so
/// items never call `Theme::for_inactive_window` themselves; reading
/// `ctx.theme` grants automatic window-blur desaturation of accent roles.
#[derive(Clone, Copy)]
pub struct SceneItemPaintContext<'a> {
    /// View pan/zoom/rotation as a single affine. Items rarely need
    /// this directly — the canvas's transform stack already accounts
    /// for it — but custom items wanting to draw at a fixed pixel
    /// size regardless of zoom can read the zoom factor from here.
    pub view_transform: Transform2D,
    /// Optional scene-coord region the renderer is currently
    /// repainting. Items that internally subdivide their geometry
    /// can use this to skip work outside the dirty region. `None`
    /// means "full repaint".
    pub dirty_scene_rect: Option<Rect>,
    /// Global accessibility text-scale factor (`1.0` = 100 %), forwarded from
    /// the widget `PaintContext`. Lightweight text items that opt in (see
    /// `TextItem::follow_text_scale`) multiply their font size by this so they
    /// grow with the app-wide "grow all text" setting. Off-by-default because
    /// the scene already has its own pan/zoom.
    pub text_scale: f32,
    /// Fully-projected theme for this paint pass. Already swapped to the
    /// inactive-window / high-contrast variant by the render walker — read it
    /// directly and never call [`Theme::for_inactive_window`] yourself. Pass
    /// to [`ColorProp::resolve`] to turn a role/reactive colour into a
    /// concrete [`Color`](teksilo_tokens::Color).
    pub theme: &'a Theme,
    /// `true` iff the host window is focused AND not occluded (`true` in
    /// headless tests). Read for behavioural blur cues the accent-desaturation
    /// theme swap can't cover (e.g. hiding a caret / muting a selection).
    pub window_active: bool,
    /// Effective enabled state of the item being painted (derived from
    /// [`ItemFlags::IS_ENABLED`]). Forwarded to [`ColorProp::resolve`] so a
    /// role-based colour picks its disabled variant on a disabled item.
    pub enabled: bool,
}

impl<'a> SceneItemPaintContext<'a> {
    /// Construct a paint context with the given view transform, optional dirty
    /// region, and the active theme. `text_scale` defaults to `1.0`,
    /// `window_active` and `enabled` to `true`; use the `with_*` builders to
    /// carry the accessibility scale, window-active state, and per-item enabled
    /// state from the widget paint pass.
    pub fn new(
        view_transform: Transform2D,
        dirty_scene_rect: Option<Rect>,
        theme: &'a Theme,
    ) -> Self {
        Self {
            view_transform,
            dirty_scene_rect,
            text_scale: 1.0,
            theme,
            window_active: true,
            enabled: true,
        }
    }

    /// Set the global accessibility text-scale factor carried to opted-in items.
    pub fn with_text_scale(mut self, text_scale: f32) -> Self {
        self.text_scale = text_scale;
        self
    }

    /// Set whether the host window is currently active (focused and unoccluded).
    pub fn with_window_active(mut self, window_active: bool) -> Self {
        self.window_active = window_active;
        self
    }

    /// Set the effective enabled state of the item being painted.
    pub fn with_enabled(mut self, enabled: bool) -> Self {
        self.enabled = enabled;
        self
    }
}

/// Context handed to [`SceneItem::accessibility`].
///
/// Carries the item's screen-projected bounds (so items wanting to
/// emit AT-relative coordinates can read them) and its `ItemId` so
/// implementations can derive synthetic AT NodeIds for sub-elements.
pub struct SceneItemA11yContext {
    /// View transform (pan/zoom/rotation) at AT-build time.
    pub view_transform: Transform2D,
    /// Item's bounds projected into screen space.
    pub screen_bounds: Rect,
    /// The id under which this item is being emitted.
    pub item_id: ItemId,
}

/// A lightweight, paint-only scene-graph item.
///
/// Implementations carry their own bounds (in local coords, anchored
/// at the origin) and provide a `paint` method that draws into a
/// [`Canvas`]. The Scene takes care of positioning, transform-chain
/// composition, hit-test, accessibility, and repaint scheduling.
///
/// # Required methods
///
/// * [`SceneItem::local_bounds`] — AABB in local item coords.
/// * [`SceneItem::set_local_bounds`] — write back the bounds field
///   when the Scene mutates it.
/// * [`SceneItem::paint`] — draw the item into the canvas. The canvas
///   already has the item's `scene_transform` pushed, so coordinates
///   are in local item space.
///
/// # Optional methods
///
/// * [`SceneItem::shape_contains`] — exact-shape hit-test in local
///   coords. Default is AABB containment.
/// * [`SceneItem::label`] — human-readable label for AT and debug.
/// * [`SceneItem::register_bindings`] — bind reactive signals to the
///   SceneView's repaint machinery.
/// * [`SceneItem::accessibility`] — populate the AccessKit node.
pub trait SceneItem: std::fmt::Debug + 'static {
    /// AABB in **local item coordinates** (origin at the item's
    /// anchor). The Scene composes this with the item's
    /// `scene_transform` to compute its scene-space AABB for the
    /// spatial index.
    fn local_bounds(&self) -> Rect;

    /// Write back new bounds. Called by `Scene::set_local_bounds`
    /// when the bounds change. Implementations update their stored
    /// bounds field; geometry-bearing items (e.g. [`crate::PathItem`])
    /// must keep their geometry consistent with the new bounds.
    fn set_local_bounds(&mut self, bounds: Rect);

    /// Paint the item into the canvas. The canvas already has this
    /// item's `scene_transform` (parent chain × view) pushed, so
    /// coordinates are in **local** item space — `(0, 0)` is the
    /// item's anchor.
    ///
    /// `ctx` carries the active [`Theme`],
    /// `window_active`, and per-item `enabled` state, so colour-bearing items
    /// resolve their [`ColorProp`] fills/strokes with
    /// `prop.resolve(ctx.theme, ctx.enabled)`.
    fn paint(&self, canvas: &mut Canvas, ctx: &SceneItemPaintContext<'_>);

    /// Replace the primary fill colour, returning `true` if this item kind has
    /// a fill slot that accepted the change. Backs
    /// [`SceneModel::set_item_fill`](crate::SceneModel::set_item_fill) /
    /// [`clear_item_fill`](crate::SceneModel::clear_item_fill). Rectangles,
    /// paths, and groups set their fill; text items map it onto their
    /// foreground colour (so a `None` is rejected — text always has a colour);
    /// image items have no fill and return `false`. Default: no-op.
    fn set_fill(&mut self, fill: Option<ColorProp>) -> bool {
        let _ = fill;
        false
    }

    /// Replace the stroke (colour + [`StrokeStyle`]), returning `true` if this
    /// item kind has a stroke slot that accepted the change. Backs
    /// [`SceneModel::set_item_stroke`](crate::SceneModel::set_item_stroke) /
    /// [`clear_item_stroke`](crate::SceneModel::clear_item_stroke). Rectangles,
    /// paths, and groups accept it; text and image items return `false`.
    /// Default: no-op.
    fn set_stroke(&mut self, stroke: Option<(ColorProp, StrokeStyle)>) -> bool {
        let _ = stroke;
        false
    }

    /// Exact-shape hit-test in **local** coordinates. Default: AABB
    /// containment via [`SceneItem::local_bounds`]. Path-based items
    /// override this to do per-segment distance checks so users can
    /// click along a stroke even when the AABB is huge.
    fn shape_contains(&self, local_pt: Point) -> bool {
        self.local_bounds().contains(local_pt)
    }

    /// Produce a stand-alone `Fn(Point, f32) -> bool` that closes over
    /// whatever state this item needs to answer `shape_contains`
    /// without retaining a borrow on `self`. The
    /// [`SceneView`](crate::SceneView) snapshots one of these for
    /// every item at layout time and consults it on every pointer
    /// event — direct calls to `shape_contains(&self, ...)` can't
    /// be cached because `&dyn SceneItem` is not `Clone`.
    ///
    /// The closure's second argument is the **view scale** (zoom)
    /// active when the pointer event arrives — passed at call time
    /// (not baked at snapshot time) because zoom changes without
    /// rebuilding the snapshot. Most items ignore it; stroke-distance
    /// hit-testing ([`PathItem`](crate::items::PathItem)) uses it so a
    /// **cosmetic** stroke (constant device-pixel width) keeps a
    /// proportionate hit band in scene coordinates at any zoom.
    ///
    /// Default: AABB containment of `local_bounds()`. Items with a
    /// non-AABB shape (notably [`crate::items::PathItem`] for
    /// stroke-only paths and [`crate::items::GroupItem`] for the
    /// logical-only / pass-through case) override this so dispatch
    /// hits along the actual painted geometry. Returning the
    /// default for an item with a custom `shape_contains` is a
    /// silent dispatch bug — the eager `Scene::item_at` path still
    /// calls `shape_contains` correctly, but pointer-event routing
    /// goes through the snapshot.
    fn clone_shape_test(&self) -> Box<dyn Fn(Point, f32) -> bool + 'static> {
        let bounds = self.local_bounds();
        Box::new(move |p, _view_scale| bounds.contains(p))
    }

    /// Dominant color to draw as the item's representation in
    /// minimap-style thumbnails. Default: an opaque mid-grey,
    /// which gives a recognisable but neutral marker for any item.
    /// Built-in items override: [`RectItem`](crate::items::RectItem)
    /// returns its fill, [`PathItem`](crate::items::PathItem)
    /// returns stroke or fill, [`ImageItem`](crate::items::ImageItem)
    /// returns the image's dominant tint placeholder.
    ///
    /// Consumed by [`Scene::item_thumbnails`](crate::Scene::item_thumbnails)
    /// — the typical minimap input. Apps with non-standard items
    /// can override on their own `SceneItem` impls.
    fn thumbnail_color(&self) -> teksilo_tokens::Color {
        teksilo_tokens::Color::new(0.6, 0.6, 0.6, 1.0)
    }

    /// The flags this item should carry into the Scene at insert
    /// time. Default: `ItemFlags::default()` — visible, enabled,
    /// selectable. Built-ins read their accumulated builder state
    /// (e.g. `.draggable(true)` flips `IS_DRAGGABLE`); custom items
    /// override this to opt into hover acceptance, focus, clipping,
    /// or `IGNORES_TRANSFORMATIONS`.
    ///
    /// Read once by [`Scene::add_item`](crate::Scene::add_item) and
    /// stored on the entry. Subsequent flag changes go through
    /// [`Scene::set_flag`](crate::Scene::set_flag) /
    /// [`Scene::set_flags`](crate::Scene::set_flags).
    fn initial_flags(&self) -> ItemFlags {
        ItemFlags::default()
    }

    /// Optional human-readable label, surfaced in debug introspection
    /// and used by the default [`SceneItem::accessibility`] impl as
    /// the AT name when an item author hasn't overridden it via the
    /// per-item `.access_label(...)` chain.
    fn label(&self) -> Option<String> {
        None
    }

    /// AT subtree treatment for descendants.
    ///
    /// `Inherit` (default) — descendants emit AT nodes normally.
    /// `Exclude` — descendants are pruned from the AT tree.
    /// `Merge` — descendants' labels concatenate into this item's
    /// AT name and they're pruned from individual emission, so the
    /// subtree reads as a single AT element. Built-ins read this
    /// from their per-item `.access_subtree(...)` chain.
    fn access_subtree_mode(&self) -> crate::items::AccessSubtreeMode {
        crate::items::AccessSubtreeMode::Inherit
    }

    /// Per-item paint caching strategy. Default
    /// [`CacheMode::None`](crate::cache::CacheMode::None): the
    /// item's `paint` runs every frame.
    ///
    /// Returning [`CacheMode::ItemCoordinate`](crate::cache::CacheMode::ItemCoordinate)
    /// asks the [`SceneView`](crate::SceneView) to record the
    /// item's paint output in **local item coordinates** as a
    /// [`RenderFrame`](teksilo_canvas::RenderFrame) and replay it on
    /// subsequent frames instead of re-running `paint`. Only
    /// suitable for items whose visual depends solely on data the
    /// Scene knows about (geometry, flags, opacity) — not on
    /// arbitrary signal state outside `local_bounds`. The cache
    /// for an id is evicted on
    /// [`ItemChange::LocalBoundsChanged`](crate::ItemChange) for
    /// that id.
    fn cache_mode(&self) -> crate::cache::CacheMode {
        crate::cache::CacheMode::None
    }

    /// Register reactive bindings the item depends on. Called once
    /// per [`SceneView::build`](crate::SceneView) for every item in
    /// the scene, with the SceneView's `WidgetId` as `view_id`. Items
    /// with signal-bound state bind their signals here at the
    /// appropriate [`BindingLevel`](teksilo_core::binding::BindingLevel).
    fn register_bindings(&self, _ctx: &mut BuildContext, _view_id: WidgetId) {}

    /// Populate the AccessKit node for this item. Default: role
    /// [`Role::GraphicsObject`] plus the [`SceneItem::label`] as the
    /// AT name if set. The per-item `.access_*` builder chain layers
    /// overrides on top of whatever this method writes.
    fn accessibility(&self, builder: &mut AccessNodeBuilder, _ctx: &SceneItemA11yContext) {
        builder.set_role(Role::GraphicsObject);
        if let Some(label) = self.label() {
            builder.set_name(label);
        }
    }
}