xnano.components.options

def get_label_text(self) -> str:
    """Return the plain-text form of ``label``."""
    label = self.label
    if isinstance(label, str):
        return label
    value = getattr(label, "value", None)
    if isinstance(value, str):
        return value
    content = getattr(label, "content", None)
    if isinstance(content, str):
        return content
    return str(label)

def get_value(self) -> Any:
    """Return the stored value, falling back to the plain label."""
    if self.value is not None:
        return self.value
    return self.get_label_text()

def select_value(self, value: Any) -> bool:
    """Select the visible item whose stored value equals ``value``.

    Returns ``True`` when a match is found. The stable way to keep a
    selection pinned across item rebuilds: store the value, rebuild
    ``items``, then re-select by value.
    """
    for index, (item_index, _) in enumerate(self._filtered()):
        if _item_value(self.items[item_index]) == value:
            self.selected = index
            return True
    return False

def resolve_submission(self, typed: str) -> str:
    """Reconcile typed composer text with the selection per ``accept``.

    Removes the userland "did they Tab-complete this row or type past
    it?" logic. See ``AcceptPolicy`` for the per-policy behavior.
    """
    typed = typed or ""
    selected = self.selected_label
    if self.accept == "extend" or not selected:
        return typed
    if self.accept == "replace":
        return selected
    # if_prefix_only
    typed_stripped = typed.strip()
    selected_stripped = selected.strip()
    if not typed_stripped:
        return selected
    typed_lower = typed_stripped.lower()
    selected_lower = selected_stripped.lower()
    if typed_lower == selected_lower or typed_lower.startswith(
        selected_lower + " "
    ):
        return typed
    if selected_lower.startswith(typed_lower):
        return selected
    return selected

def move(self, delta: int) -> None:
    """Move ``selected`` by ``delta``, skipping disabled entries.

    Movement stays within the currently filtered choices.

    Args:
        delta: Steps to move; negative moves toward the start.
    """
    visible = self._filtered()
    visible_count = len(visible)
    if visible_count == 0:
        self.selected = 0
        return
    current = max(0, min(self.selected, visible_count - 1))
    if delta == 0:
        self.selected = current
        return
    step = 1 if delta > 0 else -1
    remaining = abs(delta)
    index = current
    while remaining > 0:
        next_index = index + step
        if next_index < 0 or next_index >= visible_count:
            break
        index = next_index
        item_index = visible[index][0]
        if not _item_disabled(self.items[item_index]):
            remaining -= 1
    self.selected = index
    # If we landed on a disabled entry (all remaining disabled),
    # snap back to the nearest enabled neighbor.
    self._ensure_enabled_selection()

def select(self, index: int) -> None:
    """Set ``selected`` to ``index`` within the filtered view.

    Disabled entries are rejected; the selection is left unchanged
    when ``index`` points at a disabled item. Out-of-range indices
    are clamped.

    Args:
        index: Target index in the filtered view.
    """
    visible = self._filtered()
    if not visible:
        self.selected = 0
        return
    clamped = max(0, min(index, len(visible) - 1))
    item_index = visible[clamped][0]
    if _item_disabled(self.items[item_index]):
        return
    self.selected = clamped

def clear_query(self) -> None:
    """Clear the filter query and reset selection to the first row."""
    self.query = ""
    self.selected = 0
    self._ensure_enabled_selection()

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Apply a keyboard event while this Options is focused.

    Up/down move the selection (skipping disabled); Home/End jump
    to the first/last enabled entry. Printable characters and
    backspace edit ``query`` when ``searchable``. Enter, tab,
    escape, and ``passthrough`` bindings are never consumed so hooks
    and focus navigation see them.

    Args:
        keyboard: The keyboard event payload.

    Returns:
        ``True`` when the event was consumed.
    """
    kind = keyboard.kind
    if kind is not None and kind not in ("press", "repeat"):
        return False
    if self.passthrough and keyboard.matches(*self.passthrough):
        return False
    if keyboard.matches("enter", "tab", "escape", "esc"):
        return False

    visible_count = len(self._filtered())
    if keyboard.matches("up"):
        self.move(-1)
        return True
    if keyboard.matches("down"):
        self.move(1)
        return True
    if keyboard.matches("home"):
        self.selected = self._first_enabled_index()
        return True
    if keyboard.matches("end"):
        self.selected = self._last_enabled_index() if visible_count else 0
        return True
    if not self.searchable:
        return False
    if keyboard.matches("backspace"):
        self.query = self.query[:-1]
        self.selected = 0
        self._ensure_enabled_selection()
        return True
    character = keyboard.character
    modifiers = keyboard.modifiers
    if (
        character is not None
        and len(character) == 1
        and character.isprintable()
        and character not in ("\n", "\r", "\t")
        # ctrl/alt chords are app shortcuts, not search text.
        and "ctrl" not in modifiers
        and "alt" not in modifiers
    ):
        self.query = self.query + character
        self.selected = 0
        self._ensure_enabled_selection()
        return True
    return False

def compose(self, ctx: "ComponentRenderContext") -> Any:
    """Compose interface-neutral Content for this Options.

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

    Returns:
        An ``Items`` list, or a vertical ``Stack`` with a query row
        above the list when ``searchable``.
    """
    from xnano.core.content import Stack

    visible = self._filtered()
    available = ctx.area.height - (1 if self.searchable else 0)
    if available > 0 and len(visible) > available:
        selected = max(0, min(self.selected, len(visible) - 1))
        start = min(
            max(selected - available // 2, 0),
            len(visible) - available,
        )
        window = visible[start : start + available]
        self._visible_start = start
        hovered = self.hovered
        self.selected = selected - start
        if hovered is not None:
            self.hovered = hovered - start
        try:
            items_content = self._compose_items(ctx, visible=window)
        finally:
            self.selected = selected
            self.hovered = hovered
    else:
        self._visible_start = 0
        items_content = self._compose_items(ctx, visible=visible)
    if not self.searchable:
        return items_content
    return Stack(
        children=(self._compose_query_row(), items_content),
        direction="vertical",
        z=self.z,
        visible=self.visible,
    )

def after_render(self, ctx: "ComponentRenderContext", area: Any) -> None:
    """Record the painted area so hover can map a pointer to a row."""
    self._content_area = area

def handle_hover(self, x: int, y: int) -> bool:
    """Mark the row under the pointer as hovered (mouse hover).

    Hover is a *distinct* indicator from the selection: the hovered row
    is set here and drawn with a dim ``hover_symbol``. Moving off the
    rows clears it. Returns whether the hovered row changed.
    """
    del x  # rows span the full width; only the row (y) matters
    area = self._content_area
    if area is None:
        return False
    pairs = self._filtered()
    # The query row (searchable) sits above the items; skip it.
    top = area.y + (1 if self.searchable else 0)
    row = y - top
    visible_count = min(
        len(pairs) - self._visible_start,
        max(0, area.height - (1 if self.searchable else 0)),
    )
    if self.direction == "bottom_to_top" and visible_count:
        row = (visible_count - 1) - row
    hovered = (
        self._visible_start + row
        if pairs and 0 <= row < visible_count
        else None
    )
    if hovered != self.hovered:
        self.hovered = hovered
        return True
    return False

def component_post_init(self) -> None:
    """Initialize subclass state after dataclass fields are assigned.

    Override this method instead of ``__post_init__``.
    """
    return None

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

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

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