xnano.components.loader

def component_post_init(self) -> None:
    """Resolve spinner frames and start the animation epoch."""
    if self.style not in ("spinner", "bar", "line"):
        raise ValueError(f"Unsupported loader style: {self.style!r}")
    if self.interval <= 0:
        raise ValueError("Loader interval must be greater than zero.")
    self._resolved_symbols = resolve_loader_symbols(self.symbols)
    self._epoch_ns = time.monotonic_ns()
    self._frozen_frame = 0

def restart(self) -> None:
    """Reset the spinner epoch to the current monotonic time."""
    self._epoch_ns = time.monotonic_ns()
    self._frozen_frame = 0

def current_frame(self) -> str:
    """Return the active spinner glyph, advanced by the framework clock.

    The inline path: embed this in any ``Text``/flow content to animate a
    spinner mid-line without a manual per-tick frame counter — e.g.
    ``Text(content=f"{loader.current_frame()} generating…")``.
    """
    return self._resolved_symbols[self._spinner_frame_index()]

def inline_text(self) -> str:
    """Return the spinner glyph plus its label for inline embedding."""
    label = self._resolve_label_text()
    frame = self.current_frame()
    return frame if not label else f"{frame} {label}"

def compose(self, ctx: "ComponentRenderContext"):
    """Compose spinner text or gauge content for this loader.

    Returns:
        Interface-neutral content for this loader.
    """
    if self.style == "spinner":
        return self._compose_spinner()
    if self.value is None:
        # Indeterminate bar/line: pulse the active spinner frame as
        # the gauge label while progress stays at zero.
        frame = self._resolved_symbols[self._spinner_frame_index()]
        label = self._resolve_label_text()
        pulse_label = frame if label is None else f"{frame} {label}"
        if self.style == "line":
            return LineGauge(
                progress=0.0,
                label=pulse_label,
                foreground=self.foreground,
                filled_color=self.filled_color or self.foreground,
                unfilled_color=self.unfilled_color,
                background=self.background,
                z=self.z,
                visible=self.visible,
            )
        return Gauge(
            progress=0.0,
            label=pulse_label,
            foreground=self.foreground,
            background=self.background,
            z=self.z,
            visible=self.visible,
        )
    return self._compose_determinate()

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