bootstack 0.1.0a6__tar.gz → 0.1.0a7__tar.gz

{bootstack-0.1.0a6/src/bootstack.egg-info → bootstack-0.1.0a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.1.0a6
+Version: 0.1.0a7
 Summary: A full UI framework for Python desktop apps built on tkinter — rich widgets, theming, and application structure out of the box.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT
@@ -150,7 +150,7 @@ bs.Button(app, text="+1", command=lambda: counter.set(counter.get() + 1))
 
 ## Features
 
-- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, frameless windows with custom chrome
+- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, undecorated windows with custom chrome
 - **60+ themed widgets** — ttk-derived primitives plus higher-level composites (TableView, Calendar, DateEntry, Form, FloodGauge, Meter, ToggleGroup, PageStack, Toast, Tooltip, and more)
 - **9 dialogs** — Message, Query, ColorChooser, ColorDropper, DateDialog, FontDialog, FilterDialog, FormDialog, plus a `Dialog` base
 - **Layout containers** — `PackFrame` and `GridFrame` for declarative layouts; `ScrollView`, `PanedWindow`, `Accordion`, `Card`, `Expander`

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/README.md

@@ -116,7 +116,7 @@ bs.Button(app, text="+1", command=lambda: counter.set(counter.get() + 1))
 
 ## Features
 
-- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, frameless windows with custom chrome
+- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, undecorated windows with custom chrome
 - **60+ themed widgets** — ttk-derived primitives plus higher-level composites (TableView, Calendar, DateEntry, Form, FloodGauge, Meter, ToggleGroup, PageStack, Toast, Tooltip, and more)
 - **9 dialogs** — Message, Query, ColorChooser, ColorDropper, DateDialog, FontDialog, FilterDialog, FormDialog, plus a `Dialog` base
 - **Layout containers** — `PackFrame` and `GridFrame` for declarative layouts; `ScrollView`, `PanedWindow`, `Accordion`, `Card`, `Expander`

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.1.0a6"
+version = "0.1.0a7"
 description = "A full UI framework for Python desktop apps built on tkinter — rich widgets, theming, and application structure out of the box."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -82,7 +82,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.1.0a6"
+current_version = "0.1.0a7"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre}{pre_n}",

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/src/bootstack/__init__.py

@@ -45,7 +45,7 @@ from ttkbootstrap_icons_bs import BootstrapIcon  # noqa: E402
 # (see constants.py which re-exports from core.constants)
 
 if TYPE_CHECKING:
-    from bootstack.api.menu import MenuManager, create_menu
+    from bootstack.api.menu import MenuManager, create_menu, create_menu_items
     from bootstack.api.app import App, AppShell, App as Window, Toplevel, AppSettings, get_app_settings, get_current_app, Shortcuts, Shortcut, get_shortcuts
     from bootstack.api.style import (
         Font,
@@ -157,7 +157,7 @@ _MODULE_EXPORTS = {
     # Application & Windows (includes menu and shortcuts)
     "bootstack.api.app": [
         "App", "AppShell", "Toplevel", "Window", "AppSettings", "get_app_settings", "get_current_app",
-        "MenuManager", "create_menu",
+        "MenuManager", "create_menu", "create_menu_items",
         "Shortcuts", "Shortcut", "get_shortcuts",
     ],
     # Style & Theming

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/src/bootstack/api/__init__.py

@@ -64,7 +64,7 @@ from bootstack.api.widgets import (
 )
 from bootstack.runtime.app import App, App as Window
 from bootstack.runtime.toplevel import Toplevel
-from bootstack.runtime.menu import MenuManager, create_menu
+from bootstack.runtime.menu import MenuManager, create_menu, create_menu_items
 
 __all__ = [
     "BootstrapIcon",
@@ -122,6 +122,7 @@ __all__ = [
     "get_theme_provider",
     "get_theme_color",
     "create_menu",
+    "create_menu_items",
     "TK_WIDGETS",
     "TTK_WIDGETS",
 ]

bootstack-0.1.0a7/src/bootstack/api/menu.py

@@ -0,0 +1,7 @@
+"""Public menu-related API surface."""
+
+from __future__ import annotations
+
+from bootstack.runtime.menu import MenuManager, create_menu, create_menu_items
+
+__all__ = ["MenuManager", "create_menu", "create_menu_items"]

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/src/bootstack/core/localization/intl_format.py

@@ -429,8 +429,8 @@ class IntlFormatter:
         opt = self._normalize_date_spec(spec)
         typ = opt["type"]
         if typ == "custom": return format_time(t, format=opt["pattern"], locale=self.locale)
-        if typ == "longTime": return format_time(t, "long", self.locale)
-        if typ == "shortTime": return format_time(t, "short", self.locale)
+        if typ == "longTime": return format_time(t, "long", locale=self.locale)
+        if typ == "shortTime": return format_time(t, "short", locale=self.locale)
         if typ == "hour": return format_time(t, "H", self.locale)
         if typ == "minute": return format_time(t, "m", self.locale)
         if typ == "second": return format_time(t, "s", self.locale)
@@ -451,8 +451,8 @@ class IntlFormatter:
         if typ == "shortDateShortTime": return format_datetime(dt, "short", self.locale)
         if typ == "longDate": return format_date(dt.date(), "long", self.locale)
         if typ == "shortDate": return format_date(dt.date(), "short", self.locale)
-        if typ == "longTime": return format_time(dt.time(), "long", self.locale)
-        if typ == "shortTime": return format_time(dt.time(), "short", self.locale)
+        if typ == "longTime": return format_time(dt.time(), "long", locale=self.locale)
+        if typ == "shortTime": return format_time(dt.time(), "short", locale=self.locale)
         if typ == "monthAndDay": return format_date(dt.date(), "MMMM d", self.locale)
         if typ == "monthAndYear": return format_date(dt.date(), "MMMM y", self.locale)
         if typ == "quarterAndYear": return format_date(dt.date(), "QQQ y", self.locale)

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/src/bootstack/dialogs/datedialog.py

@@ -202,13 +202,16 @@ class DateDialog:
             show_week_numbers: bool = False,
             hide_window_chrome: bool = False,
             close_on_click_outside: bool = False,
+            selection_mode: Literal["single", "range"] = "single",
+            start_date: Optional[date | datetime | str] = None,
+            end_date: Optional[date | datetime | str] = None,
     ) -> None:
         """Create a date selection dialog.
 
         Args:
             master: Parent widget; positions dialog relative to it when set.
             title: Dialog window title text.
-            initial_date: Initial date shown; defaults to `date.today()`.
+            initial_date: Initial date shown in single mode; defaults to `date.today()`.
             first_weekday: First weekday index (0=Monday, 6=Sunday).
             accent: Calendar accent token (e.g., `primary`, `secondary`).
             disabled_dates: Iterable of dates to disable selection.
@@ -221,6 +224,11 @@ class DateDialog:
                 decorations using override-redirect.
             close_on_click_outside: When True, closes the dialog when focus
                 moves outside (popover mode).
+            selection_mode: `'single'` for a single date (default) or `'range'`
+                for a start/end date range. In range mode `result` is a
+                `tuple[date, date]` rather than a `date`.
+            start_date: Initial range start date (range mode only).
+            end_date: Initial range end date (range mode only).
         """
         self._master = master
         self._first_weekday = first_weekday
@@ -233,6 +241,9 @@ class DateDialog:
         self._show_week_numbers = show_week_numbers
         self._hide_window_chrome = hide_window_chrome
         self._close_on_click_outside = close_on_click_outside
+        self._selection_mode = selection_mode
+        self._start_date = start_date
+        self._end_date = end_date
 
         self._picker: Optional[_DialogCalendar] = None
 
@@ -253,7 +264,9 @@ class DateDialog:
 
         self._picker = _DialogCalendar(
             master=container,
-            start_date=self._initial_date,
+            selection_mode=self._selection_mode,
+            start_date=self._start_date if self._selection_mode == "range" else self._initial_date,
+            end_date=self._end_date if self._selection_mode == "range" else None,
             first_weekday=self._first_weekday,
             accent=self._accent,
             disabled_dates=self._disabled_dates,
@@ -275,16 +288,29 @@ class DateDialog:
             return
 
         payload = getattr(event, "data", None)
-        selected = None
-        if isinstance(payload, dict):
-            selected = payload.get("date") or payload.get("result")
 
-        selected = selected or self._picker.get()
-        if selected is None:
-            return
+        if self._selection_mode == "range":
+            range_data = None
+            if isinstance(payload, dict):
+                range_data = payload.get("range")
+            if range_data is None:
+                range_data = self._picker.get_range()
+            start, end = range_data if range_data else (None, None)
+            # Wait for both dates before confirming
+            if start is None or end is None:
+                return
+            result: date | Tuple[date, date] = (start, end)
+        else:
+            selected = None
+            if isinstance(payload, dict):
+                selected = payload.get("date") or payload.get("result")
+            selected = selected or self._picker.get()
+            if selected is None:
+                return
+            result = selected
 
-        self._dialog.result = selected
-        self._emit_result(selected, confirmed=True)
+        self._dialog.result = result
+        self._emit_result(result, confirmed=True)
         if self._dialog.toplevel:
             top = self._dialog.toplevel
             try:
@@ -354,8 +380,8 @@ class DateDialog:
         )
 
     @property
-    def result(self) -> Optional[date]:
-        """The selected date, or None if cancelled."""
+    def result(self) -> Optional[Union[date, Tuple[date, date]]]:
+        """The selected date (single mode) or ``(start, end)`` tuple (range mode), or None if cancelled."""
         return self._dialog.result
 
     def on_result(self, callback: Callable[[date], None]) -> Optional[str]:

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/src/bootstack/dialogs/dialog.py

@@ -130,7 +130,7 @@ class Dialog:
               its parent (via `transient`). Falls back to plain modal
               behavior on Windows/Linux where there's no equivalent.
             Defaults to "modal".
-        frameless: If True, removes window decorations (title bar, borders) and adds
+        undecorated: If True, removes window decorations (title bar, borders) and adds
             a solid border frame around the dialog content. Useful for dropdown-style
             menus or popover UIs. Defaults to False.
         window_style: Windows-only pywinstyles effect. Options include
@@ -151,7 +151,7 @@ class Dialog:
             resizable: tuple[bool, bool] | None = (False, False),
             alert: bool = False,
             mode: DialogMode = "modal",
-            frameless: bool = False,
+            undecorated: bool = False,
             window_style: str | None = None,
     ):
         import tkinter
@@ -166,7 +166,7 @@ class Dialog:
         self._resizable = resizable
         self._alert = alert
         self._mode = mode
-        self._frameless = frameless
+        self._undecorated = undecorated
         self._window_style = window_style
 
         self._toplevel: Toplevel | None = None
@@ -316,17 +316,17 @@ class Dialog:
         if self._resizable is not None:
             self._toplevel.resizable(*self._resizable)
 
-        if self._frameless:
+        if self._undecorated:
             self._toplevel.overrideredirect(True)
             self._border_frame = bs.Frame(self._toplevel, show_border=True, padding=2)
             self._border_frame.pack(fill='both', expand=True)
 
     def _build_content(self):
-        parent = self._border_frame if self._frameless else self._toplevel
-        padding = 2 if self._frameless else 0
+        parent = self._border_frame if self._undecorated else self._toplevel
+        padding = 2 if self._undecorated else 0
         self._content = bs.Frame(parent, padding=padding)
 
-        if self._frameless:
+        if self._undecorated:
             self._content.pack(fill="both", side="top", expand=False)
         else:
             self._content.pack(fill="both", side="top", expand=True)
@@ -335,8 +335,8 @@ class Dialog:
             self._content_builder(self._content)
 
     def _build_footer(self):
-        parent = self._border_frame if self._frameless else self._toplevel
-        footer_padding = 6 if self._frameless else 4
+        parent = self._border_frame if self._undecorated else self._toplevel
+        footer_padding = 6 if self._undecorated else 4
 
         if self._footer_builder:
             self._footer = bs.Frame(parent, padding=footer_padding)

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/src/bootstack/dialogs/filterdialog.py

@@ -2,7 +2,7 @@
 
 This module provides a multi-select dialog with optional search and select-all
 functionality. Items can be displayed with checkboxes, and the dialog supports
-both standard and frameless (borderless) display modes.
+both standard and undecorated (custom-chrome) display modes.
 """
 
 from tkinter import Widget
@@ -194,7 +194,7 @@ class FilterDialog(ttk.Frame):
             items: list[str | dict[str, Any]] = None,
             enable_search: bool = False,
             enable_select_all: bool = False,
-            frameless: bool = False
+            undecorated: bool = False
     ):
         """Initialize the FilterDialog.
 
@@ -207,7 +207,7 @@ class FilterDialog(ttk.Frame):
                 - selected (bool): Initial selection state (defaults to False)
             enable_search: If True, includes a search box to filter items by text.
             enable_select_all: If True, includes a "Select All" checkbox.
-            frameless: If True, removes window decorations and displays with a
+            undecorated: If True, removes window decorations and displays with a
                 border frame. Enables dismiss-on-outside-click behavior.
         """
         super().__init__(master)
@@ -216,7 +216,7 @@ class FilterDialog(ttk.Frame):
         self._items = items or []
         self._enable_search = enable_search
         self._enable_select_all = enable_select_all
-        self._frameless = frameless
+        self._undecorated = undecorated
         self._content: FilterDialogContent | None = None
         self._dialog: Dialog | None = None
         self.result: list[Any] | None = None
@@ -229,12 +229,12 @@ class FilterDialog(ttk.Frame):
             enable_select_all=self._enable_select_all,
             items=self._items
         )
-        padding = 0 if self._frameless else 10
+        padding = 0 if self._undecorated else 10
         self._content.pack(fill='both', expand=True, padx=padding, pady=padding)
 
-        # Setup dismiss-on-click for frameless after dialog is built
-        if self._frameless:
-            parent.after(10, self._setup_frameless_dismiss)
+        # Setup dismiss-on-click for undecorated after dialog is built
+        if self._undecorated:
+            parent.after(10, self._setup_undecorated_dismiss)
 
     def _on_ok(self, dialog: Dialog):
         """Save selected items to result when OK button is clicked."""
@@ -278,9 +278,9 @@ class FilterDialog(ttk.Frame):
         except:
             pass
 
-    def _setup_frameless_dismiss(self):
-        """Setup dismiss-on-outside-click for frameless dialogs."""
-        if self._frameless and self._dialog and self._dialog.toplevel:
+    def _setup_undecorated_dismiss(self):
+        """Setup dismiss-on-outside-click for undecorated dialogs."""
+        if self._undecorated and self._dialog and self._dialog.toplevel:
             # Bind to root window to catch all clicks
             root = self._dialog.toplevel.winfo_toplevel()
             while root.master:
@@ -343,7 +343,7 @@ class FilterDialog(ttk.Frame):
             maxsize=(250, 380),
             resizable=(False, True),
             mode="modal",
-            frameless=self._frameless
+            undecorated=self._undecorated
         )
 
         self._dialog.show(

{bootstack-0.1.0a6 → bootstack-0.1.0a7}/src/bootstack/runtime/menu.py

@@ -245,19 +245,18 @@ class MenuManager:
         """Create a menu from a list of item dictionaries.
 
         Args:
-            parent: The parent widget (Window, Toplevel, or Menu).
+            parent: The parent widget (Window, Toplevel, or Menu). Used as the
+                Tk parent for the created ``tk.Menu``; the menu is NOT
+                automatically attached to the parent — the caller decides
+                (e.g. ``widget['menu'] = m`` or ``MenuButton(menu=m)``).
             items: List of menu item dictionaries defining the menu structure.
 
         Returns:
             The created Menu object.
         """
-        menubar = None
-
-        # If parent is a window, create the menubar first
         if not isinstance(parent, tk.Menu):
-            menubar = tk.Menu(parent, tearoff=0)
-            parent['menu'] = menubar
-            parent = menubar  # Now work with the menubar
+            menu_root = tk.Menu(parent, tearoff=0)
+            parent = menu_root
 
         for options in items:
             options = options.copy()
@@ -305,7 +304,7 @@ class MenuManager:
             # Add all sub-items to this menu
             self._add_menu_items(menu, sub_items)
 
-        return parent if isinstance(parent, tk.Menu) else menubar
+        return parent
 
     def _add_menu_items(self, menu: tk.Menu, items: list[dict]):
         """Add items to a menu with icon support and theme tracking."""
@@ -363,148 +362,102 @@ class MenuManager:
         self.menu_items[item_id] = (menu, index, icon_name, icon_size)
 
 
-def create_menu(parent: Any, items: list[dict]) -> tk.Menu:
+def create_menu_items(items: list[dict], menu: tk.Menu = None) -> tk.Menu:
+    """Add flat or mixed items to a menu with icon and theme support.
+
+    Populates *menu* declaratively — flat commands, separators, and nested
+    cascades are all supported.  Icons and theme-color updates are handled
+    automatically via ``MenuManager``.
+
+    Args:
+        items: List of item dicts.  Supported keys: ``label``, ``icon``,
+            ``command``, ``type`` (``'command'``, ``'checkbutton'``,
+            ``'radiobutton'``, ``'separator'``), ``variable``, ``value``,
+            ``shortcut``, ``accelerator``, ``items`` (nested cascade).
+        menu: ``tk.Menu`` to populate.  If ``None``, a new ``tk.Menu`` is
+            created under the current app (``get_current_app()``).  For a
+            secondary window or dialog, pass a ``bs.Menu(dialog, tearoff=0)``
+            explicitly so icon tracking stays on the correct window.
+
+    Returns:
+        The populated ``tk.Menu``.
+
+    Example::
+
+        bs.MenuButton(app, text="File", menu=bs.create_menu_items(items)).pack()
+    """
+    if menu is None:
+        from bootstack.runtime.app import get_current_app
+        menu = tk.Menu(get_current_app(), tearoff=0)
+    root = menu.winfo_toplevel() if hasattr(menu, 'winfo_toplevel') else menu
+    if not hasattr(root, '_menu_manager'):
+        root._menu_manager = MenuManager(root)
+    root._menu_manager._add_menu_items(menu, items)
+    return menu
+
+
+def create_menu(items: list[dict], parent: Any = None) -> tk.Menu:
     """Create a menu with icon and theme support.
 
-    This is a convenience function that creates or retrieves a MenuManager
-    for the parent window and uses it to build a menu from a declarative
-    structure. The resulting menu automatically updates icon colors when
-    the theme changes.
-
-    Each menu item is defined by a dictionary that can contain:
-        - **label** (str): The text displayed for the menu item
-        - **icon** (str or dict): Icon specification. Can be a string icon
-          name (e.g., "folder2-open") or a dict with 'name' and 'size' keys
-          (e.g., {"name": "folder2-open", "size": 20})
-        - **items** (list): List of submenu items for cascade menus
-        - **command** (callable): Callback function executed when clicked
-        - **type** (str): Menu item type - 'command', 'checkbutton',
-          'radiobutton', or 'separator'
-        - **variable** (Variable): Tkinter variable for checkbutton/radiobutton
-        - **value** (Any): Value for radiobutton items
-        - **name** (str): Optional Tcl widget name for the cascade. On macOS
-          three names trigger system-native menu integration: `'apple'`
-          gives you the application menu (Tk auto-fills it with About,
-          Hide, Hide Others, Show All, Quit; any items you add appear
-          before the system items), `'window'` gets auto-populated with
-          open Toplevels, and `'help'` enables system Help search.
-          Ignored on Win/Linux.
-        - **shortcut** (str): Platform-aware accelerator. Accepts a
-          registered shortcut key (e.g. `'save'` if you've called
-          `Shortcuts.register('save', 'Mod+S', save_file)`) or a
-          modifier pattern like `'Mod+S'`, `'Ctrl+Shift+N'`, `'F5'`.
-          Renders as `⌘S` on macOS and `Ctrl+S` on Win/Linux.
-          For the actual keypress binding, register the shortcut and call
-          `Shortcuts.bind_to(app)` — that's the canonical pathway.
-        - **accelerator** (str): Legacy literal display string passed
-          straight through to `tk.Menu` (e.g. `'Ctrl+S'`). No platform
-          translation. Prefer `shortcut` for new code. If both are
-          provided, `accelerator` wins.
-        - Any other valid Tkinter menu item options (underline, etc.)
+    Builds a ``tk.Menu`` populated with cascade entries from *items*.  Icons
+    and theme-color updates are handled automatically via ``MenuManager``.
+
+    The returned menu is not attached to anything — pass it to a
+    ``MenuButton``, assign it as a window menubar, or use it however you like.
+
+    Each top-level dict in *items* becomes a cascade (submenu group).  Items
+    inside ``"items"`` are the actual commands.  Supported keys per dict:
+
+    - **label** (str): Display text (message tokens are auto-translated).
+    - **icon** (str or dict): Bootstrap icon name, e.g. ``"folder2-open"``,
+      or ``{"name": "folder2-open", "size": 18}`` for a custom size.
+    - **items** (list): Nested sub-items — creates a cascade.
+    - **command** (callable): Callback for ``'command'`` items.
+    - **type** (str): ``'command'`` (default), ``'checkbutton'``,
+      ``'radiobutton'``, or ``'separator'``.
+    - **variable** (Variable): Tk variable for checkbutton / radiobutton.
+    - **value**: Value for radiobutton items.
+    - **shortcut** (str): Platform-aware accelerator, e.g. ``'Mod+S'``.
+      Renders as ``⌘S`` on macOS and ``Ctrl+S`` on Win/Linux.
+    - **accelerator** (str): Literal accelerator string (legacy, no
+      platform translation). Prefer ``shortcut`` for new code.
+    - **name** (str): Tcl widget name for the cascade. On macOS, ``'apple'``,
+      ``'window'``, and ``'help'`` trigger system-native menu integration.
 
     Args:
-        parent: The parent widget (Window, Toplevel, or Menu). If a Window
-            or Toplevel is provided, the menu becomes the window's menubar.
-            If a Menu is provided, items are added to that menu.
-        items: List of dictionaries defining the menu structure. Each
-            dictionary represents a menu item with its configuration.
+        items: List of dicts defining the cascade structure.
+        parent: Tk parent for the created ``tk.Menu`` and the window whose
+            ``MenuManager`` tracks icon theme updates.  Defaults to the
+            current app (``get_current_app()``).  Pass a specific
+            ``Toplevel`` or dialog when building a menu for a secondary
+            window so icon tracking stays on the correct window.
 
     Returns:
-        The created Menu object. For window menubars, this is the menubar
-        itself. For menus attached to other widgets, this is the menu.
+        The created ``tk.Menu``.
 
     Examples:
-        Basic menubar with icons:
-            ```python
-            import bootstack as bs
-
-            app = bs.App()
-
-            menu_items = [
-                {
-                    "label": "File",
-                    "items": [
-                        {"label": "New", "icon": "file-plus", "command": new_file},
-                        {"label": "Open", "icon": "folder2-open", "command": open_file},
-                        {"type": "separator"},
-                        {"label": "Exit", "icon": "x-circle", "command": app.quit}
-                    ]
-                },
-                {
-                    "label": "Edit",
-                    "items": [
-                        {"label": "Undo", "icon": "arrow-counterclockwise"},
-                        {"label": "Redo", "icon": "arrow-clockwise"}
-                    ]
-                }
-            ]
+        MenuButton (single-window app — parent optional)::
 
-            bs.create_menu(app, menu_items)
-            app.mainloop()
-            ```
-
-        Nested submenus with custom icon sizes:
-            ```python
-            menu_items = [
-                {
-                    "label": "File",
-                    "items": [
-                        {
-                            "label": "Recent",
-                            "icon": {"name": "clock-history", "size": 18},
-                            "items": [
-                                {"label": "Document 1.txt"},
-                                {"label": "Document 2.txt"}
-                            ]
-                        }
-                    ]
-                }
-            ]
-            ```
-
-        Menu with checkbuttons and radiobuttons:
-            ```python
-            view_var = bs.BooleanVar(value=True)
-            theme_var = bs.StringVar(value="light")
-
-            menu_items = [
-                {
-                    "label": "View",
-                    "items": [
-                        {
-                            "label": "Show Toolbar",
-                            "type": "checkbutton",
-                            "variable": view_var
-                        }
-                    ]
-                },
-                {
-                    "label": "Theme",
-                    "items": [
-                        {
-                            "label": "Light",
-                            "type": "radiobutton",
-                            "variable": theme_var,
-                            "value": "light"
-                        },
-                        {
-                            "label": "Dark",
-                            "type": "radiobutton",
-                            "variable": theme_var,
-                            "value": "dark"
-                        }
-                    ]
-                }
-            ]
-            ```
+            bs.MenuButton(app, text="Menu", menu=bs.create_menu(items)).pack()
+
+        Window menubar::
+
+            app['menu'] = bs.create_menu(items)
+
+        Menu for a dialog (pass the Toplevel explicitly)::
+
+            dlg = bs.Toplevel(app)
+            bs.MenuButton(dlg, text="Menu", menu=bs.create_menu(items, parent=dlg)).pack()
     """
-    # Get or create MenuManager for this window
-    root = parent.winfo_toplevel() if hasattr(parent, 'winfo_toplevel') else parent
+    if parent is None:
+        from bootstack.runtime.app import get_current_app
+        parent = get_current_app()
 
+    root = parent.winfo_toplevel() if hasattr(parent, 'winfo_toplevel') else parent
     if not hasattr(root, '_menu_manager'):
         root._menu_manager = MenuManager(root)
 
     return root._menu_manager.create_menu(parent, items)
 
 
-__all__ = ['create_menu']
+__all__ = ['create_menu', 'create_menu_items']