SLeeLa GUI Menu Contract
Scope
SLGuiMenuBar, SLGuiMenu, and SLGuiMenuItem are toolkit-neutral menu state models available in version-mual, version-gual, version-thual, version-dual, and version-military.
Widget Vocabulary
menubar/menu-bar: horizontal menu-bar surface.menu: menu container.menuitem/menu-item: actionable button-like entry.menuseparator/menu-separator: horizontal separator.
The factories use existing uiBox, uiButton, and uiSeparator primitives. The menu and menu-bar tags are recognized as container surfaces; menuitem/menu-item tags are included in host activation polling and raise the ordinary CLICK event through SLGuiHostAdapter. This is the portable custom-widget fallback; native OS menu rendering still requires the Java/native host to implement the corresponding bridge behavior.
Model Responsibilities
- Menu bar: stable name, menu count, visibility, focus, opened menu index, next/previous navigation.
- Menu: stable id and label, item count, visibility, open/dismiss, bounded selection, next/previous navigation.
- Menu item: id/label, named action and operation, optional shortcut/icon metadata, enabled state, checkable/checked state, separator state, and one-shot activation latch.
A menu item is activatable only if enabled, not a separator, and configured with a non-empty action name. The host/runtime should consume takeActivation() once and dispatch the item’s named action/operation through the existing action system. Menu model state does not itself execute arbitrary operations.
Backend Capability
SLGuiBackend.supportsNativeMenus() returns true for JavaFX (javafx/fx) and the native backend. It is an eligibility/capability signal, not proof that a given host binary currently renders native menus. Swing and any host without native menu integration must use the custom-widget fallback.
Interaction Contract
The shared SLGuiMenuBar model in all five GUI versions exposes the same
controller-level state transitions:
toggle(index): open the requested top-level menu, switch to another open menu, or close the same menu when it is clicked again.dismissIfOutside(pointerInsideMenuRegion): close only when the pointer is outside the entire menu-bar and popup region. The host must classify this region as a whole; a click on a menu item must not trigger outside dismissal.escape(): dismiss an open menu and preserve menu-bar focus for predictable keyboard continuation.activated(): close after a successful ordinary menu-item activation.navigate(direction): move between top-level menus, wrapping at either end.
These methods are toolkit-neutral state transitions. They do not manufacture
pointer coordinates or keyboard events; the host must call them from real input
events. This keeps the model testable and avoids inventing a premature
OFFCLICK event type. Existing CLICK remains the normal activation event.
Integration Checklist
- Mount the menu bar above the window content and preserve menu ordering.
- Keep exactly one active top-level popup per menu bar.
- Route pointer activation and Enter/Space through the same named-action latch.
- Send outside-click classification to the menu controller once per pointer event, using the combined bar-and-popup bounds.
- Support Escape dismissal, arrow-key navigation, and focus restoration.
- Close menus after successful ordinary activation; preserve checked state for checkable items.
- Render disabled entries and separators distinctly and expose accessible names/roles.
- If native menus are unavailable, render the same model with custom widgets.
- Do not execute the operation string as code; resolve it through the application's registered action table.
- Test the same behavior on each supported host/backend before claiming native menus are complete.
Visual Quality Baseline
- Use a full-width, single-row menu bar; dropdown contents flow vertically.
- Preserve the shared base palette from
SLGuiTheme; depth tokens are a transitional layer and must not fork the chrome colors between GUI versions. - Give dropdowns restrained elevation: a soft shadow, a fine one-pixel edge, and a slightly lifted surface. The effect should separate the popup from the page without looking like a floating card detached from its menu heading.
- Use a small corner radius (nominally 6 px) and a short transition (nominally 120 ms) for opacity/elevation where the host supports it. Avoid bounce, large blur, perspective transforms, and long animations.
- Give menu items a minor pressed-depth response: a subtle surface shift and at most a one-pixel visual depression/raise. Do not move layout geometry or cause neighboring items to jump.
- Keep the popup surface
#292D35, edge#505866, hover#343A44, pressed#252A32, and highlight#3A404Bconsistent across versions. These are menu-specific transitional tokens, not replacements for base chrome colors. - Provide clear hover, keyboard-focus, pressed/open, disabled, checked, and separator states. Hover highlights; it must not be required to open a menu. Keyboard focus must remain visible without relying on shadow or color alone.
- Keep popup edges and item hit targets consistent, prevent clipping at window edges, and avoid popup geometry exceeding the parent/window bounds.
- Honor reduced-motion preferences when available; if not available, keep the transition short and purely decorative.
- Treat shadow, edge light, and depth as presentation only. They must not imply disabled/enabled state, security status, or action success.
- Preserve readable contrast and use spacing/alignment rather than decorative effects to establish hierarchy.
The five SLGuiTheme definitions now expose shared menu depth tokens and
accessors. These define the intended design language; a host renderer must
consume them before the effect is visible. Native and Java hosts should be
verified separately, and unsupported effects should degrade cleanly to a clear
border and hover/focus state.
Host Activation Status
The factories recognize menu surfaces as containers. menuitem and menu-item
are included in SLGuiWidgetFactory.interactive() and map to CLICK, so the
existing SLGuiHostAdapter polls their activation latches and dispatches the
same DOM event type as ordinary buttons. The military command-console example
and the dedicated menu showcase both demonstrate visible, collapsible dropdown
panels backed by the ui* widget bridge.
Limits
The SLeeLa library models now provide explicit toggle, outside-dismissal, Escape, activation-dismissal, and top-level navigation state transitions. These are not by themselves proof that every host wires those transitions to real native pointer/keyboard input. Native OS menu widgets, popup positioning, full keyboard event routing, outside-click dismissal, resolution of the model's named action/operation fields, and accessibility semantics remain host/runtime integration responsibilities and must be tested in each backend before being described as complete.