xnano.components.text

def component_post_init(self) -> None:
    """Validate modes and initialize the native editor when needed."""
    self._validate_display_modes()
    if self.input:
        self.focusable = True
    self._sync_editor_state()

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)

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 compose(
    self, ctx: ComponentRenderContext[Any]
) -> TextBlock | Native | Panel | None:
    """Compose interface-neutral content for this Text.

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

    Returns:
        A ``TextBlock``, ``Native`` editor payload, or nested content.
        When ``fill`` is set the block is wrapped in a background
        ``Panel`` so the color spans the full slot.
    """
    content = self._compose_content(ctx)
    if (
        self.fill
        and self.background is not None
        and isinstance(content, TextBlock)
    ):
        return Panel(child=content, background=self.background)
    return content

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Edit this text when it has focus.

    Passthrough bindings remain available to hooks. Read-only inputs reject
    edits, and ``max_length`` limits inserted content.

    Args:
        keyboard: The keyboard event payload.

    Returns:
        ``True`` when the key was consumed as text editing.
    """
    if self.passthrough and keyboard.matches(*self.passthrough):
        return False
    if not self.input:
        return False

    if self._editor is not None:
        return self._handle_editor_keyboard(keyboard)
    return self._handle_single_line_keyboard(keyboard)

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)

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

@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