xnano.components.link

def component_post_init(self) -> None:
    """Validate modes without forcing ``input=True``."""
    super().component_post_init()

def compose(self, ctx: ComponentRenderContext[Any]) -> TextBlock | Any:
    """Compose underlined, focus-aware link content.

    Args:
        ctx: Render-time scope for this paint.

    Returns:
        Styled ``TextBlock`` (or nested content) for this link.
    """
    modifiers = tuple(self.modifiers)
    if self.underline and "underline" not in modifiers:
        modifiers = modifiers + ("underline",)

    color = self.foreground
    if self.focused and self.focused_color is not None:
        color = self.focused_color
    elif self.visited and self.focused_color is None:
        # Mild visited cue when no focused override is set.
        if color == "blue":
            color = "magenta"

    # Temporarily apply compose styles without mutating live state
    # beyond the frame: build a plain block from the label.
    if isinstance(self.content, str):
        label = self.content if self.content else self.url
        return TextBlock.from_plain(
            label,
            foreground=color,
            background=self.background,
            modifiers=modifiers,
            horizontal_align=self.horizontal_align,
            vertical_align=self.vertical_align,
            wrap=self.wrap,
            z=self.z,
            visible=self.visible,
        )

    # Nested content: style via a short-lived attribute swap.
    previous_modifiers = self.modifiers
    previous_color = self.foreground
    object.__setattr__(self, "modifiers", modifiers)
    object.__setattr__(self, "foreground", color)
    try:
        return Text.compose(self, ctx)
    finally:
        object.__setattr__(self, "modifiers", previous_modifiers)
        object.__setattr__(self, "foreground", previous_color)

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Leave activation keys for application hooks.

    Args:
        keyboard: The keyboard event payload.

    Returns:
        Always ``False`` so enter/space and other keys bubble.
    """
    if self.passthrough and keyboard.matches(*self.passthrough):
        return False
    # Never consume activation or editing keys on a link.
    return False

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[Any]",
    area: "Area",
) -> None:
    """Record the multi-line editor caret so the terminal cursor tracks it."""
    if not (self._input_focused and self._editor is not None):
        self._cursor_position = None
        return
    row, column = self._editor.cursor()
    # ponytail: no soft-wrap/scroll accounting; clamps to the slot, which
    # is exact for a note-sized editor. Add offsets if the body scrolls.
    x = area.x + max(0, min(column, max(0, area.width - 1)))
    y = area.y + max(0, min(row, max(0, area.height - 1)))
    self._cursor_position = (x, y)

@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_paste(self, text: str) -> bool:
    """Insert pasted text at the caret of a multi-line editor.

    Args:
        text: The pasted clipboard text.

    Returns:
        ``True`` when the paste was consumed by the native editor.
    """
    if self._editor is None:
        return False
    if self.read_only:
        return True
    text = self._clamp_text(text)
    if self.max_length is not None:
        remaining = self.max_length - len(self._editor.text())
        if remaining <= 0:
            return True
        text = text[:remaining]
    self._editor.insert_text(text)
    object.__setattr__(self, "content", self._editor.text())
    return True

def get_terminal_node(
    self, ctx: ComponentRenderContext[Any]
) -> TextBlock | Native | Panel | None:
    """Return composed content for terminal compatibility.

    Args:
        ctx: Render-time scope for this paint.

    Returns:
        The same interface-neutral content as ``compose``.
    """
    return self.compose(ctx)