xnano.components.dropdown

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Open, close, search, or move through the dropdown.

    Opening keys expand a closed dropdown. Escape closes it without
    changing the selection. Enter accepts the selected value and closes
    it when ``close_on_select`` is enabled.

    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 not self.open:
        if self.open_keys and keyboard.matches(*self.open_keys):
            self.open = True
            self._ensure_enabled_selection()
            return True
        return False

    # Open: escape always dismisses without changing selection.
    if keyboard.matches("escape", "esc"):
        self.open = False
        return True

    if keyboard.matches("enter"):
        # Accept current selection; close only when configured.
        self._ensure_enabled_selection()
        if self.close_on_select:
            self.open = False
        # Bubble so application hooks can read ``value``.
        return False

    if self.close_keys and keyboard.matches(*self.close_keys):
        # Non-enter close keys (e.g. a custom binding) dismiss.
        if not keyboard.matches("enter"):
            self.open = False
            return True

    # While open, reuse Options movement / filter handling.
    return super().handle_keyboard(keyboard)

def compose(self, ctx: "ComponentRenderContext") -> Any:
    """Compose closed label or open options content.

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

    Returns:
        Closed: a single ``TextBlock`` row. Open: the same content
        tree ``Options`` would produce, optionally windowed.
    """
    from xnano.core.content import Stack

    if not self.open:
        return self._compose_closed_row()

    window = self._windowed_visible()
    # Remap selected into the window for Items highlight, then
    # restore — selection state stays global on the component.
    global_selected = self.selected
    local = self._window_selected_offset(window)
    if local is not None:
        self.selected = local
    try:
        items_content = self._compose_items(ctx, visible=window)
    finally:
        self.selected = global_selected

    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 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

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

@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

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_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