yera.ui.navigation

Declare stable browser screens, placement, and contextual sidebars.

Screen definitions are shared by desktop and mobile renderers. Their tuple order defines canonical navigation order, while explicit mobile positions select and order the smaller mobile destination set.

Symbols

class ScreenDefinition — Describe one stable top-level browser destination.
class ScreenRegistry — Provide ordered iteration and immutable keyed lookup for UI screens.
class SidebarDefinition — Describe contextual sidebar content owned by a screen.

ScreenDefinition

Describe one stable top-level browser destination.

Fields

key
type: str (required)

Stable identifier used by routes and active-state rendering.

label
type: str (required)

User-facing navigation label.

href
type: str (required)

Canonical destination URL.

icon
type: str (required)

Registered icon or template key used by navigation renderers.

sidebar
type: yera.ui.navigation.SidebarDefinition | None = None

Optional contextual sidebar associated with the screen.

availability
type: Literal['available', 'coming_soon'] = 'available'

Whether the destination can currently be opened.

placement
type: Literal['primary', 'utility'] = 'primary'

Primary or utility placement in desktop navigation.

mobile_menu_order
type: int | None = None

Position in the mobile menu, or None to omit the destination from that menu.

Methods


ScreenDefinition.__init__

__init__(
    key: str,
    label: str,
    href: str,
    icon: str,
    sidebar: SidebarDefinition | None = None,
    availability: ScreenAvailability = 'available',
    placement: NavigationPlacement = 'primary',
    mobile_menu_order: int | None = None,
) → None

ScreenRegistry

Provide ordered iteration and immutable keyed lookup for UI screens.

Tuple order remains the canonical desktop order. Construction rejects duplicate stable keys and builds an immutable lookup. Availability filtering preserves tuple order, while mobile navigation uses explicit mobile_menu_order values.

Fields

screens
type: tuple[yera.ui.navigation.ScreenDefinition, ...] (required)

Screen definitions in canonical navigation order.

Methods

__post_init__ — Build the immutable screen lookup and reject duplicate keys.
__iter__ — Iterate over screens in navigation order.
__len__ — Return the number of registered screens.
__getitem__ — Look up a screen by its stable key.
available — Return screens that are currently available.
mobile_menu_screens — Return destinations assigned to mobile navigation.

ScreenRegistry.__post_init__

__post_init__() → None

Build the immutable screen lookup and reject duplicate keys.

Raises

ValueError

If two screens use the same stable key.

ScreenRegistry.__iter__

__iter__() → Iterator[ScreenDefinition]

Iterate over screens in navigation order.

Returns

type: Iterator[ScreenDefinition]

An iterator over the registered screens.

ScreenRegistry.__len__

__len__() → int

Return the number of registered screens.

Returns

type: int

The number of screens in the registry.

ScreenRegistry.__getitem__

__getitem__(
    key: str,
) → ScreenDefinition

Look up a screen by its stable key.

Parameters

key
type: str

Stable screen identifier.

Returns

type: ScreenDefinition

The matching screen definition.

ScreenRegistry.available

available() → tuple[ScreenDefinition, ...]

Return screens that are currently available.

Returns

type: tuple[ScreenDefinition, ...]

Available screens in navigation order.

ScreenRegistry.mobile_menu_screens

mobile_menu_screens() → tuple[ScreenDefinition, ...]

Return destinations assigned to mobile navigation.

Screens without a mobile position are omitted. Remaining screens are sorted by their explicit mobile_menu_order rather than desktop registry order.

Returns

type: tuple[ScreenDefinition, ...]

Mobile-menu screens ordered by their configured position.

ScreenRegistry.__init__

__init__(
    screens: tuple[ScreenDefinition, ...],
) → None

SidebarDefinition

Describe contextual sidebar content owned by a screen.

Fields

key
type: str (required)

Stable sidebar context identifier.

endpoint
type: str (required)

HTMX endpoint that renders the sidebar fragment.

default_open
type: bool = False

Whether the shell initially exposes the sidebar.

Methods


SidebarDefinition.__init__

__init__(
    key: str,
    endpoint: str,
    default_open: bool = False,
) → None