Make layout_column_wrap(*args, width=)'s width come after *args

Related: rstudio/bslib#853

Author: schloerke

CHANGELOG.md

@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### API changes
 
 * Added `shiny.ui.navset_underline()` and `shiny.ui.navset_card_underline()` whose navigation container is similar to `shiny.ui.navset_tab()` and `shiny.ui.navset_card_tab()` respectively, but its active/focused navigation links are styled with an underline. (#772)
+* `shiny.ui.layout_column_wrap(width, *args)` was rearranged to `shiny.ui.layout_column_wrap(*args, width)`. Now, `width` will default to `200px` is no value is provided. (#772)
 
 * TODO-barret-API; `shiny.ui.panel_main()` and `shiny.ui.panel_sidebar()` are deprecated in favor of new API for `shiny.ui.layout_sidebar()`. Please use `shiny.ui.sidebar()` to construct a sidebar and supply it (along with the main content) to `shiny.ui.layout_sidebar(*args, **kwargs)`. (#680)
 

shiny/ui/_layout.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
-from typing import Literal, Optional
+from typing import Literal, Optional, cast
 
 from htmltools import Tag, TagAttrs, TagAttrValue, TagChild, css, div
 
+from .._deprecated import warn_deprecated
+from ..types import MISSING, MISSING_TYPE
 from ._html_deps_shinyverse import components_dependency
 from ._tag import consolidate_attrs
 from ._utils import is_01_scalar
@@ -13,8 +15,8 @@
 
 # TODO-barret-API; Move `width` to after `args`
 def layout_column_wrap(
-    width: Optional[CssUnit],
     *args: TagChild | TagAttrs,
+    width: CssUnit | None | MISSING_TYPE = MISSING,
     fixed_width: bool = False,
     heights_equal: Literal["all", "row"] = "all",
     fill: bool = True,
@@ -36,17 +38,18 @@ def layout_column_wrap(
 
     Parameters
     ----------
+    *args
+        Unnamed arguments should be UI elements (e.g.,
+        :func:`~shiny.ui.card`). Named arguments become attributes on the
+        containing :class:`~htmltools.Tag` element.
     width
         The desired width of each card. It can be a (unit-less) number between 0 and 1
         and should be specified as `1/num`, where `num` represents the number of desired
         columns. It can be a CSS length unit representing either the minimum (when
         `fixed_width=False`) or fixed width (`fixed_width=True`). It can also be `None`,
         which allows power users to set the `grid-template-columns` CSS property
-        manually, either via a `style` attribute or a CSS stylesheet.
-    *args
-        Unnamed arguments should be UI elements (e.g.,
-        :func:`~shiny.ui.card`). Named arguments become attributes on the
-        containing :class:`~htmltools.Tag` element.
+        manually, either via a `style` attribute or a CSS stylesheet. If missing, a
+        value of `200px` will be used.
     fixed_width
         When `width` is greater than 1 or is a CSS length unit, e.g. `"200px"`,
         `fixed_width` indicates whether that `width` value represents the absolute size
@@ -83,6 +86,26 @@ def layout_column_wrap(
     """
     attrs, children = consolidate_attrs(*args, class_=class_, **kwargs)
 
+    if isinstance(width, MISSING_TYPE):
+        if len(children) > 0 and (
+            children[0] is None or is_probably_a_css_unit(children[0])
+        ):
+            # Code changed from
+            #   `layout_column_wrap(width, *args)`
+            # to
+            #   `layout_column_wrap(*args, width)`.
+            # Provide deprecation warning
+
+            # Assume an unnamed first argument that matches our expectations for
+            # `width` is actually the width argument, with a warning
+            warn_deprecated(
+                "`layout_column_wrap(*args, width=)`'s `width` parameter must be named."
+            )
+            width = cast(CssUnit, children[0])
+            children = children[1:]
+        else:
+            width = "200px"
+
     colspec: str | None = None
     if width is not None:
         if is_01_scalar(width) and width > 0.0:
@@ -133,3 +156,11 @@ def layout_column_wrap(
         tag = as_fill_item(tag)
 
     return tag
+
+
+def is_probably_a_css_unit(x: TagChild) -> bool:
+    if isinstance(x, str):
+        return False
+    if isinstance(x, CssUnit):
+        return True
+    return False

tests/pytest/test_layout_column_wrap.py

@@ -0,0 +1,18 @@
+import pytest
+
+from shiny._deprecated import ShinyDeprecationWarning
+from shiny.ui import div, layout_column_wrap
+
+X = div("42")
+Y = div("43")
+w = 1 / 2
+
+
+def test_layout_column_width_as_first_param_is_deprecated():
+    layout_column_wrap(X)
+    with pytest.warns(ShinyDeprecationWarning, match="`width` parameter must be named"):
+        layout_column_wrap(w, X)
+    layout_column_wrap(X, w, Y)
+    layout_column_wrap(X, Y, w)
+    layout_column_wrap(X, Y, width=w)
+    layout_column_wrap(X, Y, width=None)