xnano.components.scrollbar

def component_post_init(self) -> None:
    """Clamp initial lengths and position."""
    self._clamp_state()

@classmethod
def from_scroll_handle(
    cls,
    handle: "ScrollHandle",
    *,
    content_length: int | None = None,
    viewport_length: int | None = None,
    orientation: ScrollbarOrientationLike = "vertical_right",
    thumb: str | None = None,
    track: str | None = None,
    begin: str | None = None,
    end: str | None = None,
    color: "ColorLike | None" = None,
    thumb_color: "ColorLike | None" = None,
    track_color: "ColorLike | None" = None,
    begin_color: "ColorLike | None" = None,
    end_color: "ColorLike | None" = None,
    visible: bool = True,
    z: int = 0,
    fit_content: bool = True,
) -> "Scrollbar":
    """Build a scrollbar bound to a field scroll handle.

    The handle owns offset / follow mode. Callers (or the field
    controller) should pass the measured content and viewport lengths;
    the component never reaches into grid private dictionaries.

    Args:
        handle: Resolved ``ScrollHandle`` for a scrolled field.
        content_length: Total scrollable content size when known.
        viewport_length: Visible window size when known.
        orientation: Scrollbar edge placement.
        thumb: Optional thumb glyph.
        track: Optional track glyph.
        begin: Optional leading glyph.
        end: Optional trailing glyph.
        color: Overall foreground color.
        thumb_color: Thumb foreground color.
        track_color: Track foreground color.
        begin_color: Leading glyph color.
        end_color: Trailing glyph color.
        visible: Whether the scrollbar paints.
        z: Paint order relative to siblings.
        fit_content: Whether layout uses the natural scrollbar size.

    Returns:
        A ``Scrollbar`` that reads ``position`` from ``handle``.
    """
    instance = cls(
        content_length=content_length or 0,
        position=int(getattr(handle, "offset", 0) or 0),
        viewport_length=viewport_length or 0,
        orientation=orientation,
        thumb=thumb,
        track=track,
        begin=begin,
        end=end,
        color=color,
        thumb_color=thumb_color,
        track_color=track_color,
        begin_color=begin_color,
        end_color=end_color,
        visible=visible,
        z=z,
        fit_content=fit_content,
    )
    instance._scroll_handle = handle
    instance._handle_content_length = content_length
    instance._handle_viewport_length = viewport_length
    return instance

def compose(self, ctx: "ComponentRenderContext"):
    """Compose scrollbar content with a native paint fallback.

    Returns:
        Interface-neutral content for this scrollbar.
    """
    return self._compose_content()

def get_frame(self) -> Any | None:
    """Optional frame/panel chrome around composed content."""
    return None

def get_size(self, ctx: ComponentRenderContext[StateT]) -> Size:
    """Return the preferred cell size of this component."""
    return Size(width=0, height=0)

def before_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> "Area":
    """Called before rendering; returns the effective render area."""
    return area

def after_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> None:
    """Called after rendering for optional post-paint work."""
    return None

@responsive_noop
def compose_extra_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra small (< 40 cols).

    Optional responsive counterpart to :meth:`compose`. When
    overridden, it is used *instead of* ``compose`` while the window
    is in this size tier. Overriding any ``compose_*`` variant opts the
    component into breakpoint dispatch; a component that overrides none
    pays no per-frame cost.
    """
    return None

@responsive_noop
def compose_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is small (40–79 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_medium(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is medium (80–119 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is large (120–159 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_extra_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra large (>= 160 cols).

    See :meth:`compose_extra_small`.
    """
    return None

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Optional keyboard handler while focused.

    Returns:
        ``True`` when the event was consumed.
    """
    return False

def handle_paste(self, text: str) -> bool:
    """Optional paste handler while focused.

    Returns:
        ``True`` when the paste was consumed.
    """
    return False