mini-arcade-core 0.9.9__py3-none-any.whl → 1.0.0__py3-none-any.whl

mini_arcade_core/ui/menu.py

@@ -5,12 +5,19 @@ Menu system for mini arcade core.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Callable, Sequence
+from typing import Callable, Optional, Sequence
 
-from mini_arcade_core.backend import Backend, Color, Event, EventType
-from mini_arcade_core.two_d import Size2D
-
-MenuAction = Callable[[], None]
+from mini_arcade_core.backend import Backend
+from mini_arcade_core.backend.events import Event, EventType
+from mini_arcade_core.backend.keys import Key
+from mini_arcade_core.backend.types import Color
+from mini_arcade_core.engine.commands import Command, CommandQueue, QuitCommand
+from mini_arcade_core.engine.render.packet import RenderPacket
+from mini_arcade_core.runtime.context import RuntimeContext
+from mini_arcade_core.runtime.input_frame import InputFrame
+from mini_arcade_core.scenes.systems.system_pipeline import SystemPipeline
+from mini_arcade_core.sim.protocols import SimScene
+from mini_arcade_core.spaces.d2.geometry2d import Size2D
 
 
 @dataclass(frozen=True)
@@ -19,11 +26,25 @@ class MenuItem:
     Represents a single item in a menu.
 
     :ivar label (str): The text label of the menu item.
-    :ivar on_select (MenuAction): The action to perform when the item is selected.
+    :ivar on_select (BaseCommand): The action to perform when the item is selected.
     """
 
+    id: str
     label: str
-    on_select: MenuAction
+    command_factory: Callable[[], Command]
+    label_fn: Optional[Callable[[object], str]] = None
+
+    def resolved_label(self, ctx: object) -> str:
+        """
+        Get the resolved label for this menu item.
+
+        :param ctx: The current ctx instance.
+        :type ctx: object
+
+        :return: The resolved label string.
+        :rtype: str
+        """
+        return self.label_fn(ctx) if self.label_fn else self.label
 
 
 # Justification: Data container for styling options needs
@@ -104,12 +125,11 @@ class MenuStyle:
     item_font_size = 24
 
 
-# pylint: enable=too-many-instance-attributes
-
-
 class Menu:
     """A simple text-based menu system."""
 
+    # Justification: Multiple attributes for menu state
+    # pylint: disable=too-many-arguments
     def __init__(
         self,
         items: Sequence[MenuItem],
@@ -117,6 +137,7 @@ class Menu:
         viewport: Size2D | None = None,
         title: str | None = None,
         style: MenuStyle | None = None,
+        on_select: Optional[Callable[[MenuItem], None]] = None,
     ):
         """
         :param items: Sequence of MenuItem instances to display.
@@ -136,6 +157,42 @@ class Menu:
         self.title = title
         self.style = style or MenuStyle()
         self.selected_index = 0
+        self._on_select = on_select
+        self._max_content_w_seen = 0
+        self._max_button_w_seen = 0
+        self.stable_width = True
+
+    # pylint: enable=too-many-arguments
+
+    def set_items(self, items: Sequence[MenuItem]):
+        """Set the menu items.
+        :param items: Sequence of new MenuItem instances.
+        :type items: Sequence[MenuItem]
+        """
+        self.items = list(items)
+
+    def set_selected_index(self, index: int):
+        """Set the selected index of the menu.
+        :param index: New selected index.
+        :type index: int
+        """
+        if 0 <= index < len(self.items):
+            self.selected_index = index
+
+    def set_labels(self, labels: Sequence[str]):
+        """Set the labels of the menu items.
+        :param labels: Sequence of new labels for the menu items.
+        :type labels: Sequence[str]
+        """
+        for index, label in enumerate(labels):
+            if index < len(self.items):
+                item = self.items[index]
+                self.items[index] = MenuItem(
+                    id=item.id,
+                    label=label,
+                    command_factory=item.command_factory,
+                    label_fn=item.label_fn,
+                )
 
     def move_up(self):
         """Move the selection up by one item, wrapping around if necessary."""
@@ -149,8 +206,11 @@ class Menu:
 
     def select(self):
         """Select the currently highlighted item, invoking its action."""
-        if self.items:
-            self.items[self.selected_index].on_select()
+        if not self.items:
+            return
+        item = self.items[self.selected_index]
+        if self._on_select is not None:
+            self._on_select(item)
 
     def handle_event(
         self,
@@ -159,7 +219,7 @@ class Menu:
         up_key: int,
         down_key: int,
         select_key: int,
-    ):
+    ) -> bool:
         """
         Handle an input event to navigate the menu.
 
@@ -176,43 +236,19 @@ class Menu:
         :type select_key: int
         """
         if event.type != EventType.KEYDOWN or event.key is None:
-            return
+            return False
+
         if event.key == up_key:
             self.move_up()
-        elif event.key == down_key:
+            return True
+        if event.key == down_key:
             self.move_down()
-        elif event.key == select_key:
+            return True
+        if event.key == select_key:
             self.select()
+            return True
 
-    def _measure_content(self, surface: Backend) -> tuple[int, int, int]:
-        # Returns (content_width, content_height, title_height)
-        # where content is items-only (no padding)
-        if not self.items and not self.title:
-            return 0, 0, 0
-
-        max_w = 0
-        title_h = 0
-
-        if self.title:
-            tw, th = surface.measure_text(
-                self.title, self.style.title_font_size
-            )
-            max_w = max(max_w, tw)
-            title_h = th
-
-        # Items
-        for it in self.items:
-            w, _ = surface.measure_text(it.label, self.style.item_font_size)
-            max_w = max(max_w, w)
-
-        items_h = len(self.items) * self.style.line_height
-
-        # Total content height includes title block if present
-        content_h = items_h
-        if self.title:
-            content_h += title_h + self.style.title_spacing
-
-        return max_w, content_h, title_h
+        return False
 
     def draw(self, surface: Backend):
         """
@@ -226,7 +262,7 @@ class Menu:
                 "Menu requires viewport=Size2D for centering/layout"
             )
 
-        vw, vh = self.viewport.width, self.viewport.height
+        vw, vh = self.viewport
 
         # 0) Solid background (for main menus)
         if self.style.background_color is not None:
@@ -315,10 +351,17 @@ class Menu:
         else:
             max_label_w = 0
             for it in self.items:
-                w, _ = surface.measure_text(it.label)
+                w, _ = surface.measure_text(
+                    it.label, font_size=self.style.item_font_size
+                )
                 max_label_w = max(max_label_w, w)
             bw = max_label_w + self.style.button_padding_x * 2
 
+            # ✅ Sticky button width (never shrink)
+            if self.stable_width:
+                self._max_button_w_seen = max(self._max_button_w_seen, bw)
+                bw = self._max_button_w_seen
+
         bh = self.style.button_height
         gap = self.style.button_gap
 
@@ -341,10 +384,18 @@ class Menu:
 
             # Label color
             text_color = self.style.selected if selected else self.style.normal
-            tw, th = surface.measure_text(item.label)
+            tw, th = surface.measure_text(
+                item.label, font_size=self.style.item_font_size
+            )
             tx = x + (bw - tw) // 2
             ty = y + (bh - th) // 2
-            surface.draw_text(tx, ty, item.label, color=text_color)
+            surface.draw_text(
+                tx,
+                ty,
+                item.label,
+                color=text_color,
+                font_size=self.style.item_font_size,
+            )
 
     # pylint: enable=too-many-locals
 
@@ -353,25 +404,32 @@ class Menu:
         max_w = 0
         title_h = 0
 
+        # Title
         if self.title:
-            tw, th = surface.measure_text(self.title)
+            tw, th = surface.measure_text(
+                self.title, font_size=self.style.title_font_size
+            )
             max_w = max(max_w, tw)
             title_h = th
 
         if not self.items:
-            content_h = 0
-            if self.title:
-                content_h = title_h
+            content_h = title_h if self.title else 0
+            # Apply stable width even for empty items
+            if self.stable_width:
+                self._max_content_w_seen = max(self._max_content_w_seen, max_w)
+                max_w = self._max_content_w_seen
             return max_w, content_h, title_h
 
         if self.style.button_enabled:
-            # width: either fixed or auto-fit
+            # Width: fixed or auto-fit by longest label
             if self.style.button_width is not None:
                 items_w = self.style.button_width
             else:
                 max_label_w = 0
                 for it in self.items:
-                    w, _ = surface.measure_text(it.label)
+                    w, _ = surface.measure_text(
+                        it.label, font_size=self.style.item_font_size
+                    )
                     max_label_w = max(max_label_w, w)
                 items_w = max_label_w + self.style.button_padding_x * 2
 
@@ -382,7 +440,9 @@ class Menu:
             items_h = len(self.items) * bh + (len(self.items) - 1) * gap
         else:
             for it in self.items:
-                w, _ = surface.measure_text(it.label)
+                w, _ = surface.measure_text(
+                    it.label, font_size=self.style.item_font_size
+                )
                 max_w = max(max_w, w)
             items_h = len(self.items) * self.style.line_height
 
@@ -394,6 +454,11 @@ class Menu:
                 + self.style.title_margin_bottom
             )
 
+        # ✅ Sticky width (never shrink)
+        if self.stable_width:
+            self._max_content_w_seen = max(self._max_content_w_seen, max_w)
+            max_w = self._max_content_w_seen
+
         return max_w, content_h, title_h
 
     # Justification: Many arguments for text drawing utility
@@ -414,3 +479,297 @@ class Menu:
         )
 
     # pylint: enable=too-many-arguments
+
+
+# pylint: enable=too-many-instance-attributes
+
+
+@dataclass
+class MenuModel:
+    """
+    Data model for menu scenes.
+
+    :ivar selected (int): Currently selected menu item index.
+    :ivar move_cooldown (float): Cooldown time between menu moves.
+    :ivar _cooldown_timer (float): Internal timer for move cooldown.
+    """
+
+    selected: int = 0
+    move_cooldown: float = 0.12
+    _cooldown_timer: float = 0.0
+
+    def step_timer(self, dt: float):
+        """
+        Step the internal cooldown timer.
+
+        :param dt: Delta time since last update.
+        :type dt: float
+        """
+        if self._cooldown_timer > 0:
+            self._cooldown_timer = max(0.0, self._cooldown_timer - dt)
+
+    def can_move(self) -> bool:
+        """
+        Check if the menu can move selection (cooldown elapsed).
+
+        :return: True if movement is allowed, False otherwise.
+        :rtype: bool
+        """
+        return self._cooldown_timer <= 0.0
+
+    def consume_move(self):
+        """Consume a move action and reset the cooldown timer."""
+        self._cooldown_timer = self.move_cooldown
+
+
+# TODO: Solve too-many-instance-attributes warning later
+# Justification: Context for menu tick needs multiple attributes.
+# pylint: disable=too-many-instance-attributes
+@dataclass
+class MenuTickContext:
+    """
+    Context for a single tick of the menu scene.
+
+    :ivar input_frame (InputFrame): The current input frame.
+    :ivar dt (float): Delta time since last tick.
+    :ivar menu (Menu): The Menu instance.
+    :ivar model (MenuModel): The MenuModel instance.
+    :ivar commands (CommandQueue): The command queue for pushing commands.
+    :ivar intent (MenuIntent | None): The current menu intent.
+    :ivar quit_cmd_factory (callable | None): Factory for quit command.
+    :ivar packet (RenderPacket | None): The resulting render packet.
+    """
+
+    input_frame: InputFrame
+    dt: float
+
+    menu: "Menu"
+    model: "MenuModel"
+    commands: CommandQueue
+
+    # computed data that systems can write into
+    intent: "MenuIntent | None" = None
+
+    # scene hook: a callable to produce quit cmd (per scene override)
+    quit_cmd_factory: callable | None = None
+
+    # final output
+    packet: RenderPacket | None = None
+
+
+# pylint: enable=too-many-instance-attributes
+
+
+@dataclass(frozen=True)
+class MenuIntent:
+    """
+    Represents the user's intent in the menu for the current tick.
+
+    :ivar move_up (bool): Whether the user intends to move up.
+    :ivar move_down (bool): Whether the user intends to move down.
+    :ivar select (bool): Whether the user intends to select the current item.
+    :ivar quit (bool): Whether the user intends to quit the menu.
+    """
+
+    move_up: bool = False
+    move_down: bool = False
+    select: bool = False
+    quit: bool = False
+
+
+@dataclass
+class MenuInputSystem:
+    """Converts InputFrame -> MenuIntent."""
+
+    name: str = "menu_input"
+    order: int = 10
+
+    def step(self, ctx: MenuTickContext):
+        """Step the input system to extract menu intent."""
+        pressed = ctx.input_frame.keys_pressed
+        ctx.intent = MenuIntent(
+            move_up=Key.UP in pressed,
+            move_down=Key.DOWN in pressed,
+            select=(Key.ENTER in pressed) or (Key.SPACE in pressed),
+            quit=Key.ESCAPE in pressed,
+        )
+
+
+@dataclass
+class MenuNavigationSystem:
+    """Menu navigation system."""
+
+    name: str = "menu_nav"
+    order: int = 20
+
+    def step(self, ctx: MenuTickContext):
+        """Update menu selection based on intent."""
+        intent = ctx.intent
+        if intent is None:
+            return
+
+        ctx.model.step_timer(ctx.dt)
+
+        if not ctx.model.can_move():
+            return
+
+        if intent.move_up:
+            ctx.menu.move_up()
+            ctx.model.selected = ctx.menu.selected_index
+            ctx.model.consume_move()
+            return
+
+        if intent.move_down:
+            ctx.menu.move_down()
+            ctx.model.selected = ctx.menu.selected_index
+            ctx.model.consume_move()
+
+
+@dataclass
+class MenuActionSystem:
+    """Menu action execution system."""
+
+    name: str = "menu_actions"
+    order: int = 30
+
+    def step(self, ctx: MenuTickContext):
+        """Execute actions based on menu intent."""
+        intent = ctx.intent
+        if intent is None:
+            return
+
+        if intent.select and ctx.menu.items:
+            item = ctx.menu.items[ctx.menu.selected_index]
+            ctx.commands.push(item.command_factory())
+
+        if intent.quit and ctx.quit_cmd_factory is not None:
+            cmd = ctx.quit_cmd_factory()
+            if cmd is not None:
+                ctx.commands.push(cmd)
+
+
+@dataclass
+class MenuRenderSystem:
+    """Menu rendering system."""
+
+    name: str = "menu_render"
+    order: int = 100
+
+    def step(self, ctx: MenuTickContext):
+        """Set the render packet to draw the menu."""
+        ctx.packet = RenderPacket.from_ops([ctx.menu.draw])
+
+
+class BaseMenuScene(SimScene):
+    """
+    Base scene class for menu-based scenes.
+
+    :ivar model (MenuModel): The data model for the menu scene.
+    """
+
+    menu: Menu
+    systems: SystemPipeline[MenuTickContext]
+
+    def __init__(self, ctx: RuntimeContext):
+        super().__init__(ctx)
+        self.model = MenuModel()
+
+    # ---- hooks (same spirit as before) ----
+
+    @property
+    def menu_title(self) -> str | None:
+        """
+        Get the title of the menu.
+
+        :return: The menu title string, or None for no title.
+        :rtype: str | None
+        """
+        return None
+
+    def menu_style(self) -> MenuStyle:
+        """
+        Get the style configuration for the menu.
+
+        :return: The MenuStyle instance for styling the menu.
+        :rtype: MenuStyle
+        """
+        return MenuStyle()
+
+    def menu_items(self) -> list[MenuItem]:
+        """
+        Get the list of menu items for the menu.
+
+        :return: List of MenuItem instances for the menu.
+        :rtype: list[MenuItem]
+        """
+        raise NotImplementedError
+
+    def quit_command(self):
+        """
+        Get the command to execute when quitting the menu.
+
+        :return: The command to execute on quit.
+        :rtype: Command
+        """
+        # default behavior: quit game
+        return QuitCommand()
+
+    def on_enter(self):
+        self.menu = Menu(
+            self._build_display_items(),
+            viewport=self.context.services.window.size,
+            title=self.menu_title,
+            style=self.menu_style(),
+        )
+        self.menu.selected_index = self.model.selected
+        self.systems = SystemPipeline()
+        self.systems.extend(
+            [
+                MenuInputSystem(),
+                MenuNavigationSystem(),
+                MenuActionSystem(),
+                MenuRenderSystem(),
+            ]
+        )
+
+    def tick(self, input_frame: InputFrame, dt: float) -> RenderPacket:
+        items = self.menu_items()
+        if not items:
+            return RenderPacket()
+
+        self.model.step_timer(dt)
+
+        self.menu.set_items(self._build_display_items())
+        self.menu.set_selected_index(self.model.selected)
+
+        ctx = MenuTickContext(
+            input_frame=input_frame,
+            dt=dt,
+            menu=self.menu,
+            model=self.model,
+            commands=self.context.command_queue,
+            quit_cmd_factory=self.quit_command,
+        )
+
+        self.systems.step(ctx)
+
+        # always return packet from pipeline
+        return ctx.packet or RenderPacket()
+
+    def _build_display_items(self) -> list[MenuItem]:
+        """
+        Resolve dynamic labels (label_fn(ctx)) into the label field the Menu draws.
+        Keeps command_factory intact.
+        """
+        src = self.menu_items()
+        out: list[MenuItem] = []
+        for it in src:
+            out.append(
+                MenuItem(
+                    id=it.id,
+                    label=it.resolved_label(self.context),
+                    command_factory=it.command_factory,
+                    label_fn=it.label_fn,
+                )
+            )
+        return out

mini_arcade_core/utils/__init__.py

@@ -0,0 +1,10 @@
+"""
+Mini Arcade Core Utilities Package
+"""
+
+from __future__ import annotations
+
+from .deprecated_decorator import deprecated
+from .logging import logger
+
+__all__ = ["logger", "deprecated"]

mini_arcade_core/utils/deprecated_decorator.py

@@ -0,0 +1,45 @@
+"""
+Deprecated utilities for the mini-arcade-core package.
+"""
+
+from __future__ import annotations
+
+import functools
+
+from mini_arcade_core.utils.logging import logger
+
+
+def deprecated(
+    reason: str | None = None,
+    version: str | None = None,
+    alternative: str | None = None,
+):
+    """
+    Mark a function as deprecated.
+
+    :param reason: Optional reason for deprecation
+    :type reason: str | None
+
+    :param version: Optional version when it will be removed
+    :type version: str | None
+
+    :param alternative: Optional alternative function to use
+    :type alternative: str | None
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            message = f"The function {func.__name__} is deprecated"
+            if version:
+                message += f" and will be removed in version {version}"
+            if reason:
+                message += f". {reason}"
+            if alternative:
+                message += f" Use {alternative} instead."
+            logger.warning(message)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator