feat: Move navbar_options into single argument with helper navbar_options()

[gadenbuie]

Moves navbar options position, bg, inverse, underline and collapsibe into a navbar_options argument in ui.page_navbar() and ui.navset_bar(). These options can be prepared with a new helper ui.navbar_options(). Further, inverse is replaced with theme in ui.navber_options().

Reflects changes in

• feat!: Introduce navbar_options() rstudio/bslib#1141
• feat(navbar_options): Match Bootstrap 5 semantics rstudio/bslib#1146

The top-level direct arguments are now deprecated, but users can continue to use them (with a deprecation warning).

[cpsievert]

I feel somewhat on the fence about this, but would you be open to having types.NavbarOptions inherit from TypedDict? The benefit being that we wouldn't need ui.navbar_options(). FWIW, the animate argument of input_slider() follows that pattern.

[gadenbuie]

Totally open to it and it's certainly a route I thought about taking. It's a little more complicated because there are methods on NavbarOptions, so we'd need a user-facing NavbarOptions that inherits from TypedDict and a counterpart NavbarOptionsResolved (or similar name) class that resolves the user-facing options.

[gadenbuie]

It turns out it's a bit more complicated because, unlike AnimationOptions, the navbar options are not a closed set, which means we can't just call NavbarOptionsResolved(**navbar_options) without making the type checker angry.

Code sample in pyright playground

from typing import TypedDict

class NavbarOptions(TypedDict, total = False):
    underline: bool
    __extra_items__: str

def test(x: NavbarOptions) -> bool:
    return x.get("underline", False)


test({"underline": True})
test({"class": "my-class"}) # we want this to be okay
#> Argument of type "dict[str, str]" cannot be assigned to parameter "x" of type "NavbarOptions" in function "test"
#>  "class" is an undefined item in type "NavbarOptions"  (reportArgumentType)

test({"underline": True, "class": "my-class"})
#> Argument of type "dict[str, bool | str]" cannot be assigned to parameter "x" of type "NavbarOptions" in function "test"
#>  "class" is an undefined item in type "NavbarOptions"  (reportArgumentType)

It turns out there's a PEP for this but it's still in draft mode: https://peps.python.org/pep-0728/

[cpsievert]

Since the "breaking" change here could be considered more of an improvement than a regression, I'd be in favor of renaming this section to ### Changes (or even ### Improvements and putting it just after ### New features.

[gadenbuie]

I had the same thought, but we do emit deprecation warnings that say, effectively, "your current code is being deprecated, please update it". I know it's not strictly breaking but I'd personally rather read a changelog that differentiates between "you might need to take action" and "you might want to know about this" items.