`` tag whose CSS position is set to absolute (or fixed if ``fixed =
- True``). The way absolute positioning works in HTML is that absolute coordinates are
- specified relative to its nearest parent element whose position is not set to static
- (which is the default), and if no such parent is found, then relative to the page
- borders. If you're not sure what that means, just keep in mind that you may get
+ Creates a `
` tag whose CSS position is set to absolute (or fixed if ``fixed =
+ True``). In HTML, absolute coordinates are specified relative to an element's
+ nearest parent element whose position is not set to static (the default).
+ If no such parent is found, the coordinates are relative to the page borders.
+ If you're not sure what that means, just keep in mind that you may get
strange results if you use this function from inside of certain types of panels.
Parameters
----------
- args
+ *args
UI elements to include inside the panel.
top
- Distance between the top of the panel, and the top of the page or parent
+ Distance between the top of the panel and the top of the page or parent
container.
left
- Distance between the left side of the panel, and the left of the page or parent
+ Distance between the left side of the panel and the left of the page or parent
container.
right
- Distance between the right side of the panel, and the right of the page or
+ Distance between the right side of the panel and the right of the page or
parent container.
bottom
- Distance between the bottom of the panel, and the bottom of the page or parent
+ Distance between the bottom of the panel and the bottom of the page or parent
container.
width
Width of the panel.
@@ -335,7 +336,7 @@ def panel_absolute(
arrow, or ``"inherit"`` for the usual cursor behavior (including changing to an
I-beam when the cursor is over text). The default is ``"auto"``, which is
equivalent to ``"move" if draggable else "inherit"``.
- kwargs
+ **kwargs
Attributes added to the content's container tag.
Returns
@@ -351,12 +352,12 @@ def panel_absolute(
results.
Like most other distance parameters in Shiny, the position and size parameters take
- a number (interpreted as pixels) or a valid CSS size string, such as ``"100px"``
- (100 pixels) or ``"25%"``.
+ a number (interpreted as pixels) or a valid CSS size string, such as `"100px"`
+ (100 pixels) or `"25%"`.
- For arcane HTML reasons, to have the panel fill the page or parent you should
+ For arcane HTML reasons, to have the panel fill the page or parent,
specify 0 for ``top``, ``left``, ``right``, and ``bottom`` rather than the more
- obvious ``width = "100%"`` and ``height = "100%"``.
+ obvious `width = "100%"` and `height = "100%"`.
"""
style = css(
@@ -385,11 +386,14 @@ def help_text(*args: TagChild | TagAttrs, **kwargs: TagAttrValue) -> Tag:
"""
Create a help text element
+ Help text is stylized text which can be added to the user interface to provide additional explanation
+ or context. Text passed to :func:`~shiny.ui.help_text` receives the Bootstrap `help-block` class.
+
Parameters
----------
- args
+ *args
UI elements to include inside the help text.
- kwargs
+ **kwargs
Attributes to add to the text container.
Returns
diff --git a/shiny/ui/_card.py b/shiny/ui/_card.py
index aeaba298a..daa3785cd 100644
--- a/shiny/ui/_card.py
+++ b/shiny/ui/_card.py
@@ -367,7 +367,7 @@ def card_body(
class CardItem:
"""
- A wrapper around a :class:`~htmltools.Tag` object that represent the content of a
+ A wrapper around a :class:`~htmltools.Tag` object that represents the content of a
card item (e.g., :func:`~shiny.ui.card_header` or
:func:`~shiny.card_footer`).
@@ -377,15 +377,15 @@ class CardItem:
Parameters
----------
item
- A :class:`~htmltools.Tag` object that represent the content of a card item
+ A :class:`~htmltools.Tag` object that represents the content of a card item
(e.g., :func:`~shiny.ui.card_header` or
:func:`~shiny.card_footer`).
See Also
--------
* :func:`~shiny.ui.card` for creating a card component.
- * :func:`~shiny.ui.card_header` for creating a header within the card.
- * :func:`~shiny.ui.card_footer` for creating a footer within the card.
+ * :func:`~shiny.ui.card_header` for creating a header within a card.
+ * :func:`~shiny.ui.card_footer` for creating a footer within a card.
"""
def __init__(
@@ -396,7 +396,7 @@ def __init__(
def resolve(self) -> TagChild:
"""
- Resolves the `CardItem` class by returning the `item` provided at initialization.
+ Resolves an object with the `CardItem` class by returning the `item` provided at initialization.
Returns
-------
diff --git a/shiny/ui/_download_button.py b/shiny/ui/_download_button.py
index 42c5d61de..be0e92fd4 100644
--- a/shiny/ui/_download_button.py
+++ b/shiny/ui/_download_button.py
@@ -31,7 +31,7 @@ def download_button(
An icon to display on the button.
width
The width of the button.
- kwargs
+ **kwargs
Additional attributes for the button.
Returns
@@ -74,7 +74,7 @@ def download_link(
**kwargs: TagAttrValue,
) -> Tag:
"""
- Create a download button
+ Create a download button.
Parameters
----------
@@ -86,7 +86,7 @@ def download_link(
An icon to display on the button.
width
The width of the button.
- kwargs
+ **kwargs
Additional attributes for the button.
Returns
diff --git a/shiny/ui/_include_helpers.py b/shiny/ui/_include_helpers.py
index 1739bfc40..8ceebb12f 100644
--- a/shiny/ui/_include_helpers.py
+++ b/shiny/ui/_include_helpers.py
@@ -27,28 +27,31 @@ def include_js(
**kwargs: TagAttrValue,
) -> Tag:
"""
- Include a JavaScript file
+ Include a JavaScript file.
Parameters
----------
path
A path to a JS file.
method
- One of the following: ``"link"``, ``"link_files"``, or ``"inline"``. ``"link"``
- is the link to the CSS file via a :func:`~ui.tags.link` tag. This method is
- generally preferrable to ``"inline"`` since it allows the browser to cache the
- file. ``"link_files"`` is the same as ``"link"``, but also allow for the CSS
- file to request other files within ``path``'s immediate parent directory (e.g.,
- ``@import()`` another file). Note that this isn't the default behavior because
- you should **be careful not to include files in the same directory as ``path``
- that contain sensitive information**. A good general rule of thumb to follow is
- to have ``path`` be located in a subdirectory of the app directory. For example,
- if the app's source is located at ``/app/app.py``, then ``path`` should be
- somewhere like ``/app/css/custom.css`` (and all the other relevant accompanying
- 'safe' files should be located under ``/app/css/``). And finally, ``"inline"``
- is the inline the CSS file contents within a :func:`~ui.tags.style` tag.
+ One of the following:
+
+ * ``"link"`` is the link to the CSS file via a :func:`~ui.tags.link` tag. This
+ method is generally preferable to ``"inline"`` since it allows the browser to
+ cache the file.
+ * ``"link_files"`` is the same as ``"link"``, but also allow for the CSS file to
+ request other files within ``path``'s immediate parent directory (e.g.,
+ ``@import()`` another file). Note that this isn't the default behavior because
+ you should **be careful not to include files in the same directory as ``path``
+ that contain sensitive information**. A good general rule of thumb to follow
+ is to have ``path`` be located in a subdirectory of the app directory. For
+ example, if the app's source is located at ``/app/app.py``, then ``path``
+ should be somewhere like ``/app/css/custom.css`` (and all the other relevant
+ accompanying 'safe' files should be located under ``/app/css/``).
+ * ``"inline"`` is the inline the CSS file contents within a
+ :func:`~ui.tags.style` tag.
**kwargs
- Attributes which are passed on to `~ui.tags.script`
+ Attributes which are passed on to `~ui.tags.script`.
Returns
@@ -59,9 +62,10 @@ def include_js(
Note
----
This places a :func:`~ui.tags.script` tag in the :func:`~ui.tags.body` of the
- document. If instead, you want to place the tag in the :func:`~ui.tags.head` of the
- document, you can wrap it in ``head_content`` (in this case, just make sure you're
- aware that the DOM probably won't be ready when the script is executed).
+ document. If you want to place the tag in the :func:`~ui.tags.head` of the
+ document instead, you can wrap it in ``head_content`` (in this case, just
+ make sure you're aware that the DOM probably won't be ready when the script
+ is executed).
```{python}
#| eval: false
@@ -98,26 +102,29 @@ def include_css(
path: Path | str, *, method: Literal["link", "link_files", "inline"] = "link"
) -> Tag:
"""
- Include a CSS file
+ Include a CSS file.
Parameters
----------
path
A path to a CSS file.
method
- One of the following: ``"link"``, ``"link_files"``, or ``"inline"``. ``"link"``
- is the link to the CSS file via a :func:`~ui.tags.link` tag. This method is
- generally preferrable to ``"inline"`` since it allows the browser to cache the
- file. ``"link_files"`` is the same as ``"link"``, but also allow for the CSS
- file to request other files within ``path``'s immediate parent directory (e.g.,
- ``@import()`` another file). Note that this isn't the default behavior because
- you should **be careful not to include files in the same directory as ``path``
- that contain sensitive information**. A good general rule of thumb to follow is
- to have ``path`` be located in a subdirectory of the app directory. For example,
- if the app's source is located at ``/app/app.py``, then ``path`` should be
- somewhere like ``/app/css/custom.css`` (and all the other relevant accompanying
- 'safe' files should be located under ``/app/css/``). And finally, ``"inline"``
- is the inline the CSS file contents within a :func:`~ui.tags.style` tag.
+ One of the following:
+
+ * ``"link"`` is the link to the CSS file via a :func:`~ui.tags.link` tag. This
+ method is generally preferable to ``"inline"`` since it allows the browser to
+ cache the file.
+ * ``"link_files"`` is the same as ``"link"``, but also allow for the CSS file to
+ request other files within ``path``'s immediate parent directory (e.g.,
+ ``@import()`` another file). Note that this isn't the default behavior because
+ you should **be careful not to include files in the same directory as ``path``
+ that contain sensitive information**. A good general rule of thumb to follow
+ is to have ``path`` be located in a subdirectory of the app directory. For
+ example, if the app's source is located at ``/app/app.py``, then ``path``
+ should be somewhere like ``/app/css/custom.css`` (and all the other relevant
+ accompanying 'safe' files should be located under ``/app/css/``).
+ * ``"inline"`` is the inline the CSS file contents within a
+ :func:`~ui.tags.style` tag.
Returns
diff --git a/shiny/ui/_input_action_button.py b/shiny/ui/_input_action_button.py
index a2af0bc0f..b29ca7d7b 100644
--- a/shiny/ui/_input_action_button.py
+++ b/shiny/ui/_input_action_button.py
@@ -31,7 +31,7 @@ def input_action_button(
An icon to appear inline with the button/link.
width
The CSS width, e.g. '400px', or '100%'
- kwargs
+ **kwargs
Attributes to be applied to the button.
Returns
@@ -85,7 +85,7 @@ def input_action_link(
An input label.
icon
An icon to appear inline with the button/link.
- kwargs
+ **kwargs
Attributes to be applied to the link.
Returns
diff --git a/shiny/ui/_input_check_radio.py b/shiny/ui/_input_check_radio.py
index d00566364..6c330f62e 100644
--- a/shiny/ui/_input_check_radio.py
+++ b/shiny/ui/_input_check_radio.py
@@ -91,7 +91,7 @@ def input_switch(
) -> Tag:
"""
Create a switch that can be used to specify logical values. Similar to
- ~shiny.ui.input_checkbox, but implies to the user that the change will take effect
+ :func:`~shiny.ui.input_checkbox`, but implies to the user that the change will take effect
immediately.
Parameters
@@ -193,9 +193,9 @@ def input_checkbox_group(
selected
The values that should be initially selected, if any.
inline
- If `True`, the result is displayed inline
+ If `True`, the result is displayed inline.
width
- The CSS width, e.g. '400px', or '100%'
+ The CSS width, e.g. '400px', or '100%'.
Returns
-------
@@ -263,9 +263,9 @@ def input_radio_buttons(
selected
The values that should be initially selected, if any.
inline
- If ``True``, the result is displayed inline
+ If ``True``, the result is displayed inline.
width
- The CSS width, e.g. '400px', or '100%'
+ The CSS width, e.g. '400px', or '100%'.
Returns
-------
diff --git a/shiny/ui/_input_file.py b/shiny/ui/_input_file.py
index 25b93f23f..b1e8caa86 100644
--- a/shiny/ui/_input_file.py
+++ b/shiny/ui/_input_file.py
@@ -65,12 +65,12 @@ def input_file(
::: {.callout-note title="Server value"}
A list of dictionaries (one for each file upload) with the following keys:
- * name: The filename provided by the web browser. This is *not* the path to read
+ * ``name``: The filename provided by the web browser. This is *not* the path to read
to get at the actual data that was uploaded (see 'datapath').
- * size: The size of the uploaded data, in bytes.
- * type: The MIME type reported by the browser (for example, 'text/plain'), or
+ * ``size``: The size of the uploaded data, in bytes.
+ * ``type``: The MIME type reported by the browser (for example, 'text/plain'), or
empty string if the browser didn't know.
- * datapath: The path to a temp file that contains the data that was uploaded.
+ * ``datapath``: The path to a temp file that contains the data that was uploaded.
This file may be deleted if the user performs another upload operation.
:::
diff --git a/shiny/ui/_input_password.py b/shiny/ui/_input_password.py
index 7e3214ca6..fbdd49eaf 100644
--- a/shiny/ui/_input_password.py
+++ b/shiny/ui/_input_password.py
@@ -30,7 +30,7 @@ def input_password(
value
Initial value.
width
- The CSS width, e.g. '400px', or '100%'
+ The CSS width, e.g., '400px', or '100%'.
placeholder
The placeholder of the input.
diff --git a/shiny/ui/_input_select.py b/shiny/ui/_input_select.py
index 98f22d2d8..945640096 100644
--- a/shiny/ui/_input_select.py
+++ b/shiny/ui/_input_select.py
@@ -37,8 +37,10 @@
_topics = {
"Server value": """
-A list of strings, usually of length 1, with the value of the selected items. When
-``multiple=True`` and nothing is selected, this value will be ``None``.
+If `multiple=False`, the server value is a string with the value of the selected item.
+If `multiple=True`, the server value is a tuple containing the values of the
+selected items. When ``multiple=True`` and nothing is selected, this value
+will be ``None``.
"""
}
@@ -84,8 +86,10 @@ def input_selectize(
Notes
------
::: {.callout-note title="Server value"}
- A list of strings, usually of length 1, with the value of the selected items. When
- ``multiple=True`` and nothing is selected, this value will be ``None``.
+ If `multiple=False`, the server value is a string with the value of the selected item.
+ If `multiple=True`, the server value is a tuple containing the values of the
+ selected items. When ``multiple=True`` and nothing is selected, this value
+ will be ``None``.
:::
See Also
@@ -153,8 +157,10 @@ def input_select(
Notes
------
::: {.callout-note title="Server value"}
- A list of strings, usually of length 1, with the value of the selected items. When
- ``multiple=True`` and nothing is selected, this value will be ``None``.
+ If `multiple=False`, the server value is a string with the value of the selected item.
+ If `multiple=True`, the server value is a tuple containing the values of the
+ selected items. When ``multiple=True`` and nothing is selected, this value
+ will be ``None``.
:::
See Also
diff --git a/shiny/ui/_input_slider.py b/shiny/ui/_input_slider.py
index 32902817f..eeb37b389 100644
--- a/shiny/ui/_input_slider.py
+++ b/shiny/ui/_input_slider.py
@@ -98,7 +98,7 @@ def input_slider(
animate
``True`` to show simple animation controls with default settings; ``False`` not
to; or a custom settings list, such as those created using
- :class:`AnimationOptions()`.
+ :class:`~AnimationOptions`.
width
The CSS width, e.g. '400px', or '100%'
sep
@@ -132,7 +132,7 @@ def input_slider(
------
::: {.callout-note title="Server value"}
A number, date, or date-time (depending on the class of value), or in the case of
- slider range, a list of two numbers/dates/date-times.
+ slider range, a tuple of two numbers/dates/date-times.
:::
See Also
diff --git a/shiny/ui/_input_text.py b/shiny/ui/_input_text.py
index 61a328271..78da52bcd 100644
--- a/shiny/ui/_input_text.py
+++ b/shiny/ui/_input_text.py
@@ -22,7 +22,7 @@ def input_text(
spellcheck: Optional[Literal["true", "false"]] = None,
) -> Tag:
"""
- Create an input control for entry of text values
+ Create an input control for entry of text values.
Parameters
----------
@@ -33,17 +33,17 @@ def input_text(
value
Initial value.
width
- The CSS width, e.g. '400px', or '100%'
+ The CSS width, e.g., '400px', or '100%'.
placeholder
A hint as to what can be entered into the control.
autocomplete
- Whether to enable browser autocompletion of the text input (default is None).
- If None, then it will use the browser's default behavior. Other possible values
+ Whether to enable browser autocompletion of the text input (default is ``None``).
+ If `None`, then it will use the browser's default behavior. Other possible values
include "on", "off", "name", "username", and "email". See
https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete for
more.
spellcheck
- Whether to enable browser spell checking of the text input (default is None). If
+ Whether to enable browser spell checking of the text input (default is ``None``). If
None, then it will use the browser's default behavior.
Returns
@@ -108,16 +108,16 @@ def input_text_area(
value
Initial value.
width
- The CSS width, e.g. '400px', or '100%'
+ The CSS width, e.g., '400px', or '100%'.
height
- The CSS height, e.g. '400px', or '100%'
+ The CSS height, e.g., '400px', or '100%'.
cols
- Value of the visible character columns of the input, e.g. 80. This argument will
+ Value of the visible character columns of the input, e.g., 80. This argument will
only take effect if there is not a CSS width rule defined for this element; such
a rule could come from the width argument of this function or from a containing
page layout such as :func:`~shiny.ui.page_fluid`.
rows
- The value of the visible character rows of the input, e.g. 6. If the height
+ The value of the visible character rows of the input, e.g., 6. If the height
argument is specified, height will take precedence in the browser's rendering.
placeholder
A hint as to what can be entered into the control.
@@ -131,11 +131,11 @@ def input_text_area(
autocomplete
Whether to enable browser autocompletion of the text input (default is "off").
If `None`, then it will use the browser's default behavior. Other possible
- values include "on", "name", "username", and "email". See [Mozila's autocomplete
+ values include "on", "name", "username", and "email". See [Mozilla's autocomplete
documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete)
for more.
spellcheck
- Whether to enable browser spell checking of the text input (default is None). If
+ Whether to enable browser spell checking of the text input (default is ``None``). If
None, then it will use the browser's default behavior.
Returns
diff --git a/shiny/ui/_input_update.py b/shiny/ui/_input_update.py
index 22a185d9c..85571e40c 100644
--- a/shiny/ui/_input_update.py
+++ b/shiny/ui/_input_update.py
@@ -45,7 +45,7 @@
The syntax of these functions is similar to the functions that created the inputs in
the first place. For example, :func:`~shiny.ui.input_numeric` and
- :func:`~update_numeric` take a similar set of arguments.
+ :func:`~shiny.ui.update_numeric` take a similar set of arguments.
Any arguments with ``None`` values will be ignored; they will not result in any
changes to the input object on the client.
@@ -82,7 +82,7 @@ def update_action_button(
An icon to appear inline with the button/link.
session
A :class:`~shiny.Session` instance. If not provided, it is inferred via
- :func:`~shiny.session.get_current_session`.
+ :func:`~shiny.session.get_current_session`.
Note
----
@@ -909,7 +909,7 @@ def update_tooltip(
session: Optional[Session] = None,
) -> None:
"""
- Update tooltip contents
+ Update tooltip contents.
Parameters
----------
@@ -966,12 +966,12 @@ def update_popover(
----------
id
The id of the popover DOM element to update.
- args
+ *args
The new contents of the popover.
title
The new title of the popover.
show
- Opens (`True`) or closes (`False) the popover.
+ Opens (`True`) or closes (`False`) the popover.
session
A Shiny session object (the default should almost always be used).
diff --git a/shiny/ui/_insert.py b/shiny/ui/_insert.py
index c802cd741..13c4fbdd4 100644
--- a/shiny/ui/_insert.py
+++ b/shiny/ui/_insert.py
@@ -18,35 +18,31 @@ def insert_ui(
session: Optional[Session] = None,
) -> None:
"""
- Insert UI objects
+ Insert UI objects.
Parameters
----------
ui
The UI object you want to insert. This can be anything that you usually put
- inside your apps's ui function. If you're inserting multiple elements in one
+ inside your app's UI function. If you're inserting multiple elements in one
call, make sure to wrap them in either a :func:`~shiny.ui.TagList` or a
:func:`~shiny.ui.tags.div` (the latter option has the advantage that you can
give it an id to make it easier to reference or remove it later on). If you want
- to insert raw html, use :func:`~shiny.ui.HTML`.
+ to insert raw HTML, use :func:`~shiny.ui.HTML`.
selector
A string that is accepted by jQuery's selector (i.e. the string ``s`` to be
placed in a ``$(s)`` jQuery call) which determines the element(s) relative to
which you want to insert your UI object.
where
- Where your UI object should go relative to the selector:
-
- - beforeBegin: Before the selector element itself
- - afterBegin: Just inside the selector element, before its first child
- - beforeEnd: Just inside the selector element, after its last child (default)
- - afterEnd: After the selector element itself
-
- Adapted from
+ Where your UI object should go relative to the selector: "beforeBegin":
+ before the selector element itself; "beforeEnd": just inside the selector
+ element, after its last child (default); "afterEnd": after the selector
+ element itself. Adapted from
https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML.
multiple
- In case your selector matches more than one element, multiple determines whether
- Shiny should insert the UI object relative to all matched elements or just
- relative to the first matched element (default).
+ In case your selector matches more than one element, ``multiple``
+ determines whether Shiny should insert the UI object relative to all
+ matched elements or just relative to the first matched element (default).
immediate
Whether the UI object should be immediately inserted or removed, or whether
Shiny should wait until all outputs have been updated and all effects have been
@@ -95,21 +91,21 @@ def remove_ui(
session: Optional[Session] = None,
) -> None:
"""
- Remove UI objects
+ Remove UI objects.
Parameters
----------
selector
A string that is accepted by jQuery's selector (i.e. the string ``x`` to be
- placed in a ``$(x)`` jQuery call) which determines the element(s) to remove. If
+ placed in a ``$(x)`` jQuery call), which determines the element(s) to remove. If
you want to remove a Shiny input or output, note that many of these are wrapped
in ``
``s, so you may need to use a somewhat complex selector — see the
Examples below. (Alternatively, you could also wrap the inputs/outputs that you
want to be able to remove easily in a ``
`` with an id.)
multiple
- In case your selector matches more than one element, multiple determines whether
- Shiny should insert the UI object relative to all matched elements or just
- relative to the first matched element (default).
+ In case your selector matches more than one element, ``multiple`` determines
+ whether Shiny should insert the UI object relative to all matched elements
+ or just relative to the first matched element (default).
immediate
Whether the UI object should be immediately inserted or removed, or whether
Shiny should wait until all outputs have been updated and all effects have been
diff --git a/shiny/ui/_layout.py b/shiny/ui/_layout.py
index 57f422ec4..c4bce6481 100644
--- a/shiny/ui/_layout.py
+++ b/shiny/ui/_layout.py
@@ -1,6 +1,6 @@
from __future__ import annotations
-from typing import Literal, Optional, cast
+from typing import Iterable, Literal, Optional, cast
from htmltools import Tag, TagAttrs, TagAttrValue, TagChild, css, div
@@ -33,8 +33,8 @@ def layout_column_wrap(
"""
A grid-like, column-first layout
- Wraps a 1d sequence of UI elements into a 2d grid. The number of columns (and rows)
- in the grid dependent on the column `width` as well as the size of the display.
+ Wraps a 1d sequence of UI elements into a 2d grid. The number of columns
+ (and rows) in the grid depends on the column width and the size of the display.
Parameters
----------
@@ -43,21 +43,26 @@ def layout_column_wrap(
: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. If missing, a
- value of `200px` will be used.
+ The desired width of each card. It can be one of the following:
+
+ * A (unit-less) number between 0 and 1, specified as `1/num`, where `num`
+ represents the number of desired columns.
+ * A CSS length unit representing either the minimum (when `fixed_width=False`)
+ or fixed width (`fixed_width=True`).
+ * `None`, which allows power users to set the `grid-template-columns` CSS
+ property 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"`,
+ 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
of each column (`fixed_width=TRUE`) or the minimum size of a column
- (`fixed_width=FALSE`). When `fixed_width=FALSE`, new columns are added to a row
- when `width` space is available and columns will never exceed the container or
- viewport size. When `fixed_width=TRUE`, all columns will be exactly `width`
- wide, which may result in columns overflowing the parent container.
+ (`fixed_width=FALSE`).
+
+ When `fixed_width=FALSE`, new columns are added to a row when `width` space is
+ available and columns will never exceed the container or viewport size.
+
+ When `fixed_width=TRUE`, all columns will be exactly `width` wide, which may
+ result in columns overflowing the parent container.
heights_equal
If `"all"` (the default), every card in every row of the grid will have the same
height. If `"row"`, then every card in _each_ row of the grid will have the same
@@ -83,6 +88,11 @@ def layout_column_wrap(
-------
:
A :class:`~htmltools.Tag` element.
+
+ See Also
+ --------
+ * :func:`~shiny.ui.layout_columns` for laying out elements into a responsive
+ 12-column grid.
"""
attrs, children = consolidate_attrs(*args, class_=class_, **kwargs)
@@ -123,14 +133,6 @@ def layout_column_wrap(
else:
colspec = f"repeat(auto-fit, minmax(min({width_css_unit}, 100%), 1fr))"
- # Use a new dict so that we don't mutate the original `children` dict
- upgraded_children: list[TagChild] = []
- for child_value in children:
- child = div({"class": "bslib-gap-spacing"}, child_value)
- if fillable:
- child = as_fillable_container(child)
- upgraded_children.append(child)
-
tag_style_css = {
"grid-template-columns": colspec,
"grid-auto-rows": "1fr" if (heights_equal == "all") else None,
@@ -150,7 +152,7 @@ def layout_column_wrap(
"style": css(**tag_style_css),
},
attrs,
- *upgraded_children,
+ *wrap_all_in_gap_spaced_container(children, fillable),
components_dependency(),
)
if fill:
@@ -165,3 +167,23 @@ def is_probably_a_css_unit(x: TagChild) -> bool:
if isinstance_cssunit(x):
return True
return False
+
+
+def wrap_all_in_gap_spaced_container(
+ children: Iterable[TagChild],
+ fillable: bool = True,
+ class_: Optional[str] = None,
+) -> list[TagChild]:
+ item_class = "bslib-gap-spacing"
+ if class_ is not None:
+ item_class = f"{item_class} {class_}"
+
+ # Use a new list so that we don't mutate the original `children`
+ wrapped_children: list[TagChild] = []
+ for child_value in children:
+ child = div({"class": item_class}, child_value)
+ if fillable:
+ child = as_fillable_container(child)
+ wrapped_children.append(child)
+
+ return wrapped_children
diff --git a/shiny/ui/_layout_columns.py b/shiny/ui/_layout_columns.py
new file mode 100644
index 000000000..7bd2394db
--- /dev/null
+++ b/shiny/ui/_layout_columns.py
@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Dict, Iterable, Literal, Optional, Tuple, TypeVar, Union, cast
+from warnings import warn
+
+from htmltools import Tag, TagAttrs, TagAttrValue, TagChild, css
+
+from ._html_deps_shinyverse import web_component_dependency
+from ._layout import wrap_all_in_gap_spaced_container
+from ._tag import consolidate_attrs
+from .css import CssUnit, as_css_unit
+from .fill import as_fill_item
+
+T = TypeVar("T")
+
+
+Breakpoint = Literal["xs", "sm", "md", "lg", "xl", "xxl"]
+"""
+References
+----------
+* [Available Bootstrap breakpoints](https://getbootstrap.com/docs/5.3/layout/breakpoints/#available-breakpoints)
+"""
+
+
+breakpoints: Tuple[Breakpoint, ...] = ("xs", "sm", "md", "lg", "xl", "xxl")
+
+
+BreakpointsSoft = Dict[Breakpoint, Union[Iterable[T], T, None]]
+BreakpointsOptional = Dict[Breakpoint, Union[Iterable[T], None]]
+BreakpointsComplete = Dict[Breakpoint, Iterable[T]]
+BreakpointsUser = Union[BreakpointsSoft[T], Iterable[T], T, None]
+
+
+def layout_columns(
+ *args: TagChild | TagAttrs,
+ col_widths: BreakpointsUser[int] = None,
+ row_heights: BreakpointsUser[CssUnit] = None,
+ fill: bool = True,
+ fillable: bool = True,
+ gap: Optional[CssUnit] = None,
+ class_: Optional[str] = None,
+ height: Optional[CssUnit] = None,
+ **kwargs: TagAttrValue,
+) -> Tag:
+ """
+ Create responsive, column-based grid layouts, based on a 12-column grid.
+
+ Parameters
+ ----------
+ *args
+ Child elements or attributes to be added to the layout.
+ col_widths
+ The widths of the columns, possibly at different breakpoints. Can be one of the
+ following:
+
+ * `None` (the default): Automatically determines a sensible number of columns
+ based on the number of children given to the layout.
+ * A list or tuple of integers between 1 and 12, where each element represents
+ the number of columns for the relevant UI element. Column widths are recycled
+ to extend the values in `col_widths` to match the actual number of items in
+ the layout, and children are wrapped onto the next row when a row exceeds 12
+ column units. For example, `col_widths=(4, 8, 12)` allocates 4 columns to the
+ first element, 8 columns to the second element, and 12 columns to the third
+ element (which wraps to the next row). Negative values are also allowed, and
+ are treated as empty columns. For example, `col_widths=(-2, 8, -2)` would
+ allocate 8 columns to an element (with 2 empty columns on either side).
+ * A dictionary of column widths at different breakpoints. The keys should be
+ one of `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"xxl"`, and the values are
+ either of the above. For example, `col_widths={"sm": (3, 3, 6), "lg": (4)}`.
+ row_heights
+ The heights of the rows, possibly at different breakpoints. Can be one of the
+ following:
+
+ * A numeric vector, where each value represents the
+ [fractional unit](https://css-tricks.com/introduction-fr-css-unit/)
+ (`fr`) height of the relevant row. If there are more rows than values
+ provided, the pattern will be repeated. For example, `row_heights=(1, 2)`
+ allows even rows to take up twice as much space as odd rows.
+ * A list of numeric or CSS length units, where each value represents the height
+ of the relevant row. If more rows are needed than values provided, the pattern
+ will repeat. For example, `row_heights=["auto", 1]` allows the height of odd
+ rows to be driven my it's contents and even rows to be
+ [`1fr`](https://css-tricks.com/introduction-fr-css-unit/).
+ * A single string containing CSS length units. In this case, the value is
+ supplied directly to `grid-auto-rows`.
+ * A dictionary of row heights at different breakpoints, where each key is a
+ breakpoint name (one of `"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`, or `"xxl"`)
+ and where the values may be any of the above options.
+ fill
+ Whether or not to allow the layout to grow/shrink to fit a fillable container
+ with an opinionated height (e.g., :func:`~shiny.ui.page_fillable`).
+ fillable
+ Whether or not each element is wrapped in a fillable container.
+ gap
+ Any valid CSS unit to use for the gap between columns.
+ class_
+ CSS class(es) to apply to the containing element.
+ height
+ Any valid CSS unit to use for the height.
+ **kwargs
+ Additional attributes to apply to the containing element.
+
+ Returns
+ -------
+ :
+ An :class:`~htmltools.Tag` element.
+
+ See Also
+ --------
+ * :func:`~shiny.ui.layout_column_wrap` for laying out elements into a uniform grid.
+
+ Reference
+ --------
+ * [Bootstrap CSS Grid](https://getbootstrap.com/docs/5.3/layout/grid/)
+ * [Bootstrap Breakpoints](https://getbootstrap.com/docs/5.3/layout/breakpoints/)
+ """
+ attrs, children = consolidate_attrs(*args, class_=class_, **kwargs)
+
+ col_widths_spec = as_col_spec(col_widths, len(children))
+
+ # Create the bslib-layout-columns element
+ tag = Tag(
+ "bslib-layout-columns",
+ {
+ "class": "bslib-grid grid bslib-mb-spacing",
+ "style": css(
+ gap=as_css_unit(gap),
+ height=as_css_unit(height),
+ ),
+ },
+ col_widths_attrs(col_widths_spec),
+ attrs,
+ row_heights_attrs(row_heights),
+ *wrap_all_in_gap_spaced_container(children, fillable, "bslib-grid-item"),
+ web_component_dependency(),
+ )
+
+ # Apply fill to the outer layout (fillable is applied to the children)
+ if fill:
+ tag = as_fill_item(tag)
+
+ return tag
+
+
+def as_col_spec(
+ col_widths: BreakpointsUser[int],
+ n_kids: int,
+) -> BreakpointsOptional[int] | None:
+ if col_widths is None:
+ return None
+
+ if not isinstance(col_widths, Dict):
+ return {"md": validate_col_width(col_widths, n_kids, "md")}
+
+ ret: BreakpointsOptional[int] = {}
+ col_widths_items = cast(BreakpointsSoft[int], col_widths).items()
+
+ for brk, value in col_widths_items:
+ if brk not in breakpoints:
+ raise ValueError(
+ f"Breakpoint '{brk}' is not valid. Valid breakpoints are: {', '.join(breakpoints)}'."
+ )
+
+ if value is None:
+ ret[brk] = None
+ elif isinstance(value, (int, Iterable)):
+ ret[brk] = validate_col_width(value, n_kids, brk)
+ else:
+ raise TypeError(
+ f"Invalid type for value at breakpoint '{brk}'. Expected int or Iterable[int]."
+ )
+
+ return ret
+
+
+def validate_col_width(
+ x: Iterable[int] | int, n_kids: int, break_name: Breakpoint
+) -> Iterable[int]:
+ if isinstance(x, int):
+ y = [x]
+ else:
+ y = x
+
+ if not all(isinstance(i, int) for i in y):
+ raise ValueError(
+ f"Column values at breakpoint '{break_name}' must be integers. Values greater than 0 indicate width, and negative values indicate a column offset."
+ )
+
+ if any(i == 0 for i in y):
+ raise ValueError(
+ f"Column values at breakpoint '{break_name}' must be greater than 0 to indicate width, or negative to indicate a column offset."
+ )
+
+ if not any(b > 0 for b in y):
+ raise ValueError(
+ f"Column values at breakpoint '{break_name}' must include at least one positive integer width."
+ )
+
+ if len(list(y)) > n_kids:
+ warn(
+ f"More column widths than children at breakpoint '{break_name}', extra widths will be ignored."
+ )
+
+ return y
+
+
+def col_widths_attrs(col_widths: BreakpointsOptional[int] | None) -> TagAttrs:
+ ret: Dict[str, TagAttrValue] = {}
+ if col_widths is None:
+ return ret
+
+ for break_name, value in col_widths.items():
+ if isinstance(break_name, Enum):
+ break_name = break_name.value
+ break_name = f"col-widths-{break_name}"
+ if value is None:
+ ret[break_name] = ""
+ else:
+ ret[break_name] = ",".join([str(v) for v in value])
+
+ return ret
+
+
+def maybe_fr_unit(x: CssUnit) -> str:
+ if isinstance(x, float):
+ x = round(x)
+
+ if isinstance(x, int):
+ return f"{x}fr"
+
+ return x
+
+
+def row_heights_attrs(
+ x: BreakpointsUser[CssUnit],
+) -> TagAttrs:
+ if x is None:
+ return {"style": "", "class": ""}
+
+ if isinstance(x, (int, float, str)): # CssUnit
+ x = [x]
+
+ if hasattr(x, "__iter__") and not isinstance(x, Dict):
+ # For a single row_heights, we use the same value across all breakpoints,
+ # including mobile
+ height = " ".join([maybe_fr_unit(h) for h in x])
+ return {
+ "style": css(
+ **{"--bslib-grid--row-heights": height},
+ ),
+ "class": "",
+ }
+
+ x = cast(BreakpointsSoft[CssUnit], x)
+
+ # Remove any None values from x
+ x_complete = {k: v for k, v in x.items() if v is not None}
+
+ # We use classes to activate CSS variables at the right breakpoints. Note: Mobile
+ # row height is derived from xs or defaults to auto in the CSS, so we don't need the
+ # class to activate it
+ classes = [
+ f"bslib-grid--row-heights--{brk}" for brk in x_complete.keys() if brk != "xs"
+ ]
+
+ # Create CSS variables, treating numeric values as fractional units, passing strings
+ css_vars: Dict[str, str] = {}
+ for brk, heights in x_complete.items():
+ var = f"--bslib-grid--row-heights--{brk}"
+
+ if isinstance(heights, CssUnit):
+ heights = [heights]
+
+ value = " ".join([maybe_fr_unit(h) for h in heights])
+ css_vars[var] = value
+
+ return {
+ "style": css(**css_vars),
+ "class": " ".join(classes),
+ }
diff --git a/shiny/ui/_modal.py b/shiny/ui/_modal.py
index a1203255c..8f6532f33 100644
--- a/shiny/ui/_modal.py
+++ b/shiny/ui/_modal.py
@@ -18,8 +18,9 @@
def modal_button(label: TagChild, icon: TagChild = None, **kwargs: TagAttrValue) -> Tag:
"""
- Creates a button that will dismiss a :func:`modal` (useful when customising the
- ``footer`` of :func:`modal`).
+ Creates a button that will dismiss a :func:`modal`. :func:`~shiny.ui.modal_button` is usually
+ passed to the `footer` of a :func:`~shiny.ui.modal` to add a button to the footer that will close
+ the :func:`~shiny.ui.modal`.
Parameters
----------
@@ -27,7 +28,7 @@ def modal_button(label: TagChild, icon: TagChild = None, **kwargs: TagAttrValue)
An input label.
icon
An icon to appear inline with the button/link.
- kwargs
+ **kwargs
Attributes to be applied to the button.
Returns
@@ -67,29 +68,32 @@ def modal(
**kwargs: TagAttrValue,
) -> Tag:
"""
- Creates the UI for a modal dialog, using Bootstrap's modal class. Modals are
+ Creates the UI for a modal dialog, using Bootstrap's modal class.
+
+ A modal is a dialog box that appears in front of the app. Modals are
typically used for showing important messages, or for presenting UI that requires
input from the user, such as a user name and/or password input.
Parameters
----------
- args
+ *args
UI elements for the body of the modal.
title
An optional title for the modal dialog.
footer
UI for footer. Use ``None`` for no footer.
size
- One of "s" for small, "m" (the default) for medium, or "l" for large.
+ The size of the modal dialogue box. Use one of "s" for small, "m" (the default)
+ for medium, or "l" for large.
easy_close
If ``True``, the modal dialog can be dismissed by clicking outside the dialog
- box, or be pressing the Escape key. If ``False`` (the default), the modal dialog
+ box, or by pressing the Escape key. If ``False`` (the default), the modal dialog
can't be dismissed in those ways; instead it must be dismissed by clicking on a
``modal_button()``, or from a call to ``modal_remove()`` on the server.
fade
If ``False``, the modal dialog will have no fade-in animation (it will simply
appear rather than fade in to view).
- kwargs
+ **kwargs
Attributes to be applied to the modal's body tag.
Returns
@@ -156,13 +160,16 @@ def modal_show(modal: Tag, session: Optional[Session] = None) -> None:
"""
Show a modal dialog.
+ :func:`~shiny.ui.modal_show` is used to display a modal that has been
+ created with :func:`~shiny.ui.modal`.
+
Parameters
----------
modal
Typically a :func:`modal` instance.
session
- A :class:`~shiny.Session` instance. If not provided, it is inferred via
- :func:`~shiny.session.get_current_session`.
+ The :class:`~shiny.Session` instance to display the modal in. If not provided,
+ the session is inferred via :func:`~shiny.session.get_current_session`.
See Also
-------
@@ -180,13 +187,17 @@ def modal_show(modal: Tag, session: Optional[Session] = None) -> None:
def modal_remove(session: Optional[Session] = None) -> None:
"""
- Remove a modal dialog.
+ Remove a modal dialog box.
+
+ :func:`~shiny.ui.modal_remove` provides a way to remove a modal programatically.
+ Modals can also be removed manually by the user if a :func:`~shiny.ui.modal_button`
+ is provided, or if the modal is created with `easy_close=True`.
Parameters
----------
session
- A :class:`~shiny.Session` instance. If not provided, it is inferred via
- :func:`~shiny.session.get_current_session`.
+ The :class:`~shiny.Session` instance that contains the modal to remove. If not
+ provided, the session is inferred via :func:`~shiny.session.get_current_session`.
See Also
-------
diff --git a/shiny/ui/_navs.py b/shiny/ui/_navs.py
index f57338d76..8a883d164 100644
--- a/shiny/ui/_navs.py
+++ b/shiny/ui/_navs.py
@@ -1,7 +1,7 @@
from __future__ import annotations
__all__ = (
- "nav",
+ "nav_panel",
"nav_menu",
"nav_control",
"nav_spacer",
@@ -17,6 +17,7 @@
# Deprecated - 2023-08-15
"navset_pill_card",
"navset_tab_card",
+ "nav",
)
import copy
@@ -34,7 +35,6 @@
from ._card import CardItem, WrapperCallable, card, card_body, card_footer, card_header
from ._html_deps_shinyverse import components_dependency
from ._sidebar import Sidebar, layout_sidebar
-from ._tag import tag_add_style
from .css import CssUnit, as_css_padding, as_css_unit
from .fill import as_fill_item, as_fillable_container
@@ -42,7 +42,7 @@
# -----------------------------------------------------------------------------
# Navigation items
# -----------------------------------------------------------------------------
-class Nav:
+class NavPanel:
nav: Tag
content: Optional[Tag]
@@ -98,12 +98,12 @@ def tagify(self) -> None:
@add_example()
-def nav(
+def nav_panel(
title: TagChild,
*args: TagChild,
value: Optional[str] = None,
icon: TagChild = None,
-) -> Nav:
+) -> NavPanel:
"""
Create a nav item pointing to some internal content.
@@ -114,11 +114,11 @@ def nav(
*args
UI elements to display when the item is active.
value
- The value of the item. This is used to determine whether the item is active
- (when an ``id`` is provided to the nav container), programmatically select the
- item (e.g., :func:`~shiny.ui.update_navs`), and/or be provided to the
- ``selected`` argument of the navigation container (e.g.,
- :func:`~shiny.ui.navset_tab`).
+ The value of the item. Use this value to determine whether the item is active
+ (when an ``id`` is provided to the nav container) or to programmatically
+ select the item (e.g., :func:`~shiny.ui.update_navs`). You can also
+ provide the value to the ``selected`` argument of the navigation container
+ (e.g., :func:`~shiny.ui.navset_tab`).
icon
An icon to appear inline with the button/link.
@@ -151,13 +151,13 @@ def nav(
role="tab",
)
- return Nav(
+ return NavPanel(
tags.li(link),
div(*args, class_="tab-pane", role="tabpanel", data_value=value),
)
-def nav_control(*args: TagChild) -> Nav:
+def nav_control(*args: TagChild) -> NavPanel:
"""
Place a control in the navigation container.
@@ -168,7 +168,7 @@ def nav_control(*args: TagChild) -> Nav:
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_spacer
* ~shiny.ui.navset_bar
@@ -183,18 +183,18 @@ def nav_control(*args: TagChild) -> Nav:
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
- return Nav(tags.li(*args))
+ return NavPanel(tags.li(*args))
-def nav_spacer() -> Nav:
+def nav_spacer() -> NavPanel:
"""
Create space between nav items.
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.navset_bar
@@ -209,10 +209,10 @@ def nav_spacer() -> Nav:
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
- return Nav(tags.li(components_dependency(), class_="bslib-nav-spacer"))
+ return NavPanel(tags.li(components_dependency(), class_="bslib-nav-spacer"))
class NavMenu:
@@ -291,12 +291,12 @@ def menu_string_as_nav(x: str | NavSetArg) -> NavSetArg:
else:
nav = tags.li(x, class_="dropdown-header")
- return Nav(nav)
+ return NavPanel(nav)
def nav_menu(
title: TagChild,
- *args: Nav | str,
+ *args: NavPanel | str,
value: Optional[str] = None,
icon: TagChild = None,
align: Literal["left", "right"] = "left",
@@ -309,16 +309,16 @@ def nav_menu(
title
A title to display. Can be a character string or UI elements (i.e., tags).
*args
- A collection of nav items (e.g., :func:`~shiny.ui.nav`) and/or strings.
+ A collection of nav items (e.g., :func:`~shiny.ui.nav_panel`) and/or strings.
Strings will be rendered as a section header unless the string is a set
of two or more hyphens (e.g., ``---``), in which case it will be rendered
as a divider.
value
- The value of the item. This is used to determine whether the item is active
- (when an ``id`` is provided to the nav container), programmatically select the
- item (e.g., :func:`~shiny.ui.update_navs`), and/or be provided to the
- ``selected`` argument of the navigation container (e.g.,
- :func:`~shiny.ui.navset_tab`).
+ The value of the item. Use this value to determine whether the item is active
+ (when an ``id`` is provided to the nav container) or to programmatically
+ select the item (e.g., :func:`~shiny.ui.update_navs`). You can also
+ provide the value to the ``selected`` argument of the navigation container
+ (e.g., :func:`~shiny.ui.navset_tab`).
icon
An icon to appear inline with the button/link.
align
@@ -331,7 +331,7 @@ def nav_menu(
See Also
-------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
* ~shiny.ui.navset_bar
@@ -346,7 +346,7 @@ def nav_menu(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
if value is None:
value = str(title)
@@ -414,7 +414,7 @@ def navset_tab(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -429,7 +429,7 @@ def navset_tab(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -444,7 +444,7 @@ def navset_tab(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
return NavSet(
@@ -470,7 +470,7 @@ def navset_pill(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -484,7 +484,7 @@ def navset_pill(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -499,7 +499,7 @@ def navset_pill(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
return NavSet(
@@ -525,7 +525,7 @@ def navset_underline(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -539,7 +539,7 @@ def navset_underline(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -554,7 +554,7 @@ def navset_underline(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
return NavSet(
*args,
@@ -580,7 +580,7 @@ def navset_hidden(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -594,7 +594,7 @@ def navset_hidden(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -693,7 +693,7 @@ def navset_card_tab(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -702,23 +702,6 @@ def navset_card_tab(
``value``).
sidebar
A `Sidebar` component to display on every `nav()` page.
- fillable
- Whether or not to allow fill items to grow/shrink to fit the browser window. If
- `True`, all `nav()` pages are fillable. A character vector, matching the value
- of `nav()`s to be filled, may also be provided. Note that, if a `sidebar` is
- provided, `fillable` makes the main content portion fillable.
- gap
- A CSS length unit defining the gap (i.e., spacing) between elements provided to
- `*args`.
- padding
- Padding to use for the body. This can be a numeric vector (which will be
- interpreted as pixels) or a character vector with valid CSS lengths. The length
- can be between one and four. If one, then that value will be used for all four
- sides. If two, then the first value will be used for the top and bottom, while
- the second value will be used for left and right. If three, then the first will
- be used for top, the second will be left and right, and the third will be
- bottom. If four, then the values will be interpreted as top, right, bottom, and
- left respectively.
header
UI to display above the selected content.
footer
@@ -726,7 +709,7 @@ def navset_card_tab(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -741,7 +724,7 @@ def navset_card_tab(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
return NavSetCard(
@@ -773,7 +756,7 @@ def navset_card_pill(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -781,7 +764,7 @@ def navset_card_pill(
Choose a particular nav item to select by default value (should match it's
``value``).
sidebar
- A :class:`shiny.ui.Sidebar` component to display on every :func:`~shiny.ui.nav` page.
+ A :class:`shiny.ui.Sidebar` component to display on every :func:`~shiny.ui.nav_panel` page.
header
UI to display above the selected content.
footer
@@ -791,7 +774,7 @@ def navset_card_pill(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -806,7 +789,7 @@ def navset_card_pill(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
return NavSetCard(
@@ -833,12 +816,12 @@ def navset_card_underline(
placement: Literal["above", "below"] = "above",
) -> NavSetCard:
"""
- Render nav items active/focused navigation links are styled with an underline inside a card container.
+ Render nav items inside a card container. Active/focused navigation links are styled with an underline.
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -846,7 +829,7 @@ def navset_card_underline(
Choose a particular nav item to select by default value (should match it's
``value``).
sidebar
- A :class:`shiny.ui.Sidebar` component to display on every :func:`~shiny.ui.nav` page.
+ A :class:`shiny.ui.Sidebar` component to display on every :func:`~shiny.ui.nav_panel` page.
header
UI to display above the selected content.
footer
@@ -856,7 +839,7 @@ def navset_card_underline(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -871,7 +854,7 @@ def navset_card_underline(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
return NavSetCard(
*args,
@@ -935,7 +918,7 @@ def navset_pill_list(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
id
If provided, will create an input value that holds the currently selected nav
item.
@@ -953,7 +936,7 @@ def navset_pill_list(
See Also
--------
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -968,7 +951,7 @@ def navset_pill_list(
Example
-------
- See :func:`~shiny.ui.nav`
+ See :func:`~shiny.ui.nav_panel`
"""
return NavSetPillList(
@@ -1129,7 +1112,7 @@ def _make_tabs_fillable(
# must to be a fillable container.
content = as_fillable_container(as_fill_item(content))
- for child in content.children:
+ for i, child in enumerate(content.children):
# Only work on Tags
if not isinstance(child, Tag):
continue
@@ -1146,9 +1129,11 @@ def _make_tabs_fillable(
padding=as_css_padding(padding),
__bslib_navbar_margin="0;" if navbar else None,
)
- child = tag_add_style(child, styles)
+ child.add_style(cast(str, styles))
child = as_fillable_container(as_fill_item(child))
+ content.children[i] = child
+
return content
@@ -1180,7 +1165,7 @@ def navset_bar(
Parameters
----------
*args
- A collection of nav items (e.g., :func:`shiny.ui.nav`).
+ A collection of nav items (e.g., :func:`shiny.ui.nav_panel`).
title
Title to display in the navbar.
id
@@ -1190,7 +1175,7 @@ def navset_bar(
Choose a particular nav item to select by default value (should match it's
``value``).
sidebar
- A :class:`~shiny.ui.Sidebar` component to display on every :func:`~shiny.ui.nav` page.
+ A :class:`~shiny.ui.Sidebar` component to display on every :func:`~shiny.ui.nav_panel` page.
fillable
Whether or not to allow fill items to grow/shrink to fit the browser window. If
`True`, all `nav()` pages are fillable. A character vector, matching the value
@@ -1230,7 +1215,7 @@ def navset_bar(
See Also
--------
* ~shiny.ui.page_navbar
- * ~shiny.ui.nav
+ * ~shiny.ui.nav_panel
* ~shiny.ui.nav_menu
* ~shiny.ui.nav_control
* ~shiny.ui.nav_spacer
@@ -1245,7 +1230,7 @@ def navset_bar(
Example
-------
- See :func:`~shiny.ui.nav`.
+ See :func:`~shiny.ui.nav_panel`.
"""
# If args contains any lists, flatten them into args.
@@ -1394,3 +1379,24 @@ def navset_tab_card(
header=header,
footer=footer,
)
+
+
+# Deprecated 2023-12-07
+def nav(
+ title: TagChild,
+ *args: TagChild,
+ value: Optional[str] = None,
+ icon: TagChild = None,
+) -> NavPanel:
+ """Deprecated. Please use `nav_panel()` instead of `nav()`."""
+ warn_deprecated(
+ "`nav()` is deprecated. "
+ "This method will be removed in a future version, "
+ "please use :func:`~shiny.ui.nav_panel` instead."
+ )
+ return nav_panel(
+ title,
+ *args,
+ value=value,
+ icon=icon,
+ )
diff --git a/shiny/ui/_notification.py b/shiny/ui/_notification.py
index 40d4c83f7..15f9d6f50 100644
--- a/shiny/ui/_notification.py
+++ b/shiny/ui/_notification.py
@@ -25,17 +25,22 @@ def notification_show(
"""
Show a notification to the user.
+ A notification is a message that appears near the bottom corner of the app.
+ Notifications normally disappear after a short period of time, and should multiple
+ notifications appear together, they will stack on top of one another.
+
Parameters
----------
ui
- Content of message.
+ Contents of the notification message.
action
Message content that represents an action. For example, this could be a link
that the user can click on. This is separate from ui so customized layouts can
- handle the main notification content separately from action content.
+ handle the main notification content separately from the action content.
duration
Number of seconds to display the message before it disappears. Use ``None`` to
- make the message not automatically disappear.
+ prevent the message from disappearing automatically. The user will need to click
+ the corner of the notification to close it.
close_button
If ``True``, display a button which will make the notification disappear when
clicked. If ``False`` do not display.
@@ -44,11 +49,11 @@ def notification_show(
notification with the same ``id`` will be replaced with this one (otherwise, a
new notification is created).
type
- A string which controls the color of the notification. One of "default" (gray),
- "message" (blue), "warning" (yellow), or "error" (red).
+ A string which controls the color of the notification. This should be one of
+ "default" (gray), "message" (blue), "warning" (yellow), or "error" (red).
session
- A :class:`~shiny.Session` instance. If not provided, it is inferred via
- :func:`~shiny.session.get_current_session`.
+ The :class:`~shiny.Session` in which the notification should appear. If not
+ provided, the session is inferred via :func:`~shiny.session.get_current_session`.
Returns
-------
@@ -89,12 +94,16 @@ def notification_remove(id: str, *, session: Optional[Session] = None) -> str:
"""
Remove a notification.
+ :func:`~shiny.ui.notification_remove` provides a way to remove a notification programatically.
+ Notifications can also be removed manually by the user, or automatically after a
+ specififed amont of time passes.
+
Parameters
----------
id
- A notification ``id``.
+ The ``id`` of the notification to remove.
session
- A :class:`~shiny.Session` instance. If not provided, it is inferred via
+ The :class:`~shiny.Session` in which the notification appears. If not provided, the session is inferred via
:func:`~shiny.session.get_current_session`.
Returns
diff --git a/shiny/ui/_output.py b/shiny/ui/_output.py
index db780ca1b..7accac6a1 100644
--- a/shiny/ui/_output.py
+++ b/shiny/ui/_output.py
@@ -246,7 +246,7 @@ def output_text(
id
An output id.
inline
- If ``True``, the result is displayed inline
+ If ``True``, the result is displayed inline.
container
A Callable that returns the output container.
@@ -284,7 +284,8 @@ def output_text_verbatim(id: str, placeholder: bool = False) -> Tag:
An output id.
placeholder
If the output is empty or ``None``, should an empty rectangle be displayed to
- serve as a placeholder? (does not affect behavior when the output is nonempty)
+ serve as a placeholder? (This does not affect behavior when the output
+ is nonempty.)
Returns
-------
@@ -345,7 +346,7 @@ def output_ui(
id
An output id.
inline
- If ``True``, the result is displayed inline
+ If ``True``, the result is displayed inline.
container
A Callable that returns the output container.
fill
@@ -354,7 +355,7 @@ def output_ui(
fillable
Whether or not the UI output area should be considered a fillable (i.e.,
flexbox) container.
- kwargs
+ **kwargs
Attributes to be applied to the output container.
Returns
diff --git a/shiny/ui/_page.py b/shiny/ui/_page.py
index 98eee94cd..207bd1ab0 100644
--- a/shiny/ui/_page.py
+++ b/shiny/ui/_page.py
@@ -36,7 +36,7 @@
from ._tag import consolidate_attrs
from ._utils import get_window_title
from .css import CssUnit, as_css_padding, as_css_unit
-from .fill._fill import FILLABLE_CONTAINTER_ATTRS
+from .fill._fill import as_fillable_container
def page_sidebar(
@@ -56,7 +56,7 @@ def page_sidebar(
----------
sidebar
Content to display in the sidebar.
- args
+ *args
UI elements.
title
A title to display at the top of the page.
@@ -72,7 +72,7 @@ def page_sidebar(
ISO 639-1 language code for the HTML page, such as ``"en"`` or ``"ko"``. This
will be used as the lang in the ```` tag, as in ````. The
default, `None`, results in an empty string.
- kwargs
+ **kwargs
Additional attributes passed to :func:`~shiny.ui.layout_sidebar`.
Returns
@@ -135,7 +135,7 @@ def page_navbar(
Parameters
----------
- args
+ *args
UI elements.
title
The browser window title (defaults to the host URL of the page). Can also be set
@@ -144,7 +144,7 @@ def page_navbar(
If provided, will create an input value that holds the currently selected nav
item.
selected
- Choose a particular nav item to select by default value (should match it's
+ Choose a particular nav item to select by default value (should match its
``value``).
sidebar
A :func:`~shiny.ui.sidebar` component to display on every page.
@@ -261,7 +261,7 @@ def page_fillable(
**kwargs: TagAttrValue,
) -> Tag:
"""
- Creates a fillable page
+ Create a fillable page.
Parameters
----------
@@ -298,15 +298,10 @@ def page_fillable(
style = css(padding=as_css_padding(padding), gap=as_css_unit(gap))
- return page_bootstrap(
+ page = page_bootstrap(
head_content(tags.style("html { height: 100%; }")),
- # Even though page_bootstrap accepts *args/**kwargs, we need to prepend the
- # class value to the tags.body. To avoid having a within a for a
- # core code path, we can manually use `FILLABLE_CONTAINER_ATTRS` here as the
- # first set of attributes.
- FILLABLE_CONTAINTER_ATTRS,
{"class": "bslib-page-fill bslib-gap-spacing", "style": style},
- {"class": "bslib-flow-mobile"} if fillable_mobile else None,
+ {"class": "bslib-flow-mobile"} if not fillable_mobile else None,
attrs,
*children,
components_dependency(),
@@ -314,6 +309,15 @@ def page_fillable(
lang=lang,
)
+ # page returns a tag, but we need to make the fillable
+ body = page.children[1]
+ if not isinstance(body, Tag) or body.name != "body":
+ raise ValueError("Expected a tag")
+
+ page.children[1] = as_fillable_container(body)
+
+ return page
+
@add_example()
def page_fluid(
@@ -327,7 +331,7 @@ def page_fluid(
Parameters
----------
- args
+ *args
UI elements.
title
The browser window title (defaults to the host URL of the page). Can also be set
@@ -336,7 +340,7 @@ def page_fluid(
ISO 639-1 language code for the HTML page, such as ``"en"`` or ``"ko"``. This
will be used as the lang in the ```` tag, as in ````. The
default, `None`, results in an empty string.
- kwargs
+ **kwargs
Attributes on the page level container.
Returns
@@ -368,7 +372,7 @@ def page_fixed(
Parameters
----------
- args
+ *args
UI elements.
title
The browser window title (defaults to the host URL of the page). Can also be set
@@ -377,7 +381,7 @@ def page_fixed(
ISO 639-1 language code for the HTML page, such as ``"en"`` or ``"ko"``. This
will be used as the lang in the ```` tag, as in ````. The
default, `None`, results in an empty string.
- kwargs
+ **kwargs
Attributes on the page level container.
Returns
@@ -409,7 +413,7 @@ def page_bootstrap(
Parameters
----------
- args
+ *args
UI elements.
title
The browser window title (defaults to the host URL of the page). Can also be set
@@ -418,7 +422,7 @@ def page_bootstrap(
ISO 639-1 language code for the HTML page, such as ``"en"`` or ``"ko"``. This
will be used as the lang in the ```` tag, as in ````. The
default, `None`, results in an empty string.
- kwargs
+ **kwargs
Attributes on the the `` tag.
Returns
diff --git a/shiny/ui/_popover.py b/shiny/ui/_popover.py
index da11aca5e..93c476759 100644
--- a/shiny/ui/_popover.py
+++ b/shiny/ui/_popover.py
@@ -112,7 +112,6 @@ def fa_gear_icon(title: str):
See Also
--------
* 0?p++:h>r?l[l.length-1]+=Math.abs(i[h]):a[p]+=Math.abs(i[h]),h++;t.set(e,{width:c,before:a,after:l})}return t}function pt(n,t,e=12){let i=t.length;function s(r,o){t[r].classList.add(o)}for(let[r,o]of n){if(o.width.length>i){let d=`Truncating number of widths at '${r}' breakpoint to match number of elements.`;console.warn(d,{widths:o.width.length,elements:i})}let c=Ce(o.width,i),a=Ce(o.before,i),l=Ce(o.after,i),h=0,p=(d,m=!1)=>{h=Math.abs(h);let v=h+d;v==e&&(v=0),v>e&&(v=m?-1*(v%e):d),h=v};for(let d=0;d0?l[d-1]:0),C=Math.min(c[d],e),Se=e-h;v>0&&(p(v,!0),h<0&&(h=Math.abs(h),c[d]>e-h&&(h=0),Se=0),m=Se>=c[d]||h>0),h>0&&h+c[d]>e&&(m=!0,h=0),m&&s(d,r==="xs"?`g-start-${h+1}`:`g-start-${r}-${h+1}`),s(d,r==="xs"?`g-col-${C}`:`g-col-${r}-${C}`),p(C,!1)}}}function ut(n,t){let e=new Map,i=n.getAttributeNames().filter(s=>s.startsWith(t));for(let s of i)e.set(s,n.getAttribute(s));return e}function Ce(n,t){let e=Array(t).fill(0);for(let i=0;i{customElements.define(n.tagName,n),window.Shiny&&(n.isShinyInput&&Ge(n.tagName),"shinyCustomMessageHandlers"in n&&Je(n.shinyCustomMessageHandlers))});})();
/*! Bundled license information:
@lit/reactive-element/decorators/custom-element.js:
diff --git a/shiny/www/shared/bslib/components/web-components.min.js.map b/shiny/www/shared/bslib/components/web-components.min.js.map
index 71db59d16..6563deccd 100644
--- a/shiny/www/shared/bslib/components/web-components.min.js.map
+++ b/shiny/www/shared/bslib/components/web-components.min.js.map
@@ -1,7 +1,7 @@
{
"version": 3,
- "sources": ["../../../node_modules/@lit/reactive-element/src/decorators/property.ts", "../../../node_modules/@lit/reactive-element/src/decorators/query-assigned-elements.ts", "../../../node_modules/@lit/reactive-element/src/css-tag.ts", "../../../node_modules/@lit/reactive-element/src/reactive-element.ts", "../../../node_modules/lit-html/src/lit-html.ts", "../../../node_modules/lit-element/src/lit-element.ts", "../../../srcts/src/components/webcomponents/_bslibElement.ts", "../../../srcts/src/components/_utilsTooltip.ts", "../../../srcts/src/components/_shinyResizeObserver.ts", "../../../srcts/src/components/webcomponents/tooltip.ts", "../../../srcts/src/components/webcomponents/popover.ts", "../../../srcts/src/components/webcomponents/inputDarkMode.ts", "../../../srcts/src/components/webcomponents/_makeInputBinding.ts", "../../../srcts/src/components/_shinyAddCustomMessageHandlers.ts", "../../../srcts/src/components/webcomponents/index.ts"],
- "sourcesContent": ["/**\n * @license\n * Copyright 2017 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/*\n * IMPORTANT: For compatibility with tsickle and the Closure JS compiler, all\n * property decorators (but not class decorators) in this file that have\n * an @ExportDecoratedItems annotation must be defined as a regular function,\n * not an arrow function.\n */\nimport {PropertyDeclaration, ReactiveElement} from '../reactive-element.js';\nimport {ClassElement} from './base.js';\n\nconst standardProperty = (\n options: PropertyDeclaration,\n element: ClassElement\n) => {\n // When decorating an accessor, pass it through and add property metadata.\n // Note, the `hasOwnProperty` check in `createProperty` ensures we don't\n // stomp over the user's accessor.\n if (\n element.kind === 'method' &&\n element.descriptor &&\n !('value' in element.descriptor)\n ) {\n return {\n ...element,\n finisher(clazz: typeof ReactiveElement) {\n clazz.createProperty(element.key, options);\n },\n };\n } else {\n // createProperty() takes care of defining the property, but we still\n // must return some kind of descriptor, so return a descriptor for an\n // unused prototype field. The finisher calls createProperty().\n return {\n kind: 'field',\n key: Symbol(),\n placement: 'own',\n descriptor: {},\n // store the original key so subsequent decorators have access to it.\n originalKey: element.key,\n // When @babel/plugin-proposal-decorators implements initializers,\n // do this instead of the initializer below. See:\n // https://github.com/babel/babel/issues/9260 extras: [\n // {\n // kind: 'initializer',\n // placement: 'own',\n // initializer: descriptor.initializer,\n // }\n // ],\n initializer(this: {[key: string]: unknown}) {\n if (typeof element.initializer === 'function') {\n this[element.key as string] = element.initializer.call(this);\n }\n },\n finisher(clazz: typeof ReactiveElement) {\n clazz.createProperty(element.key, options);\n },\n };\n }\n};\n\nconst legacyProperty = (\n options: PropertyDeclaration,\n proto: Object,\n name: PropertyKey\n) => {\n (proto.constructor as typeof ReactiveElement).createProperty(name, options);\n};\n\n/**\n * A property decorator which creates a reactive property that reflects a\n * corresponding attribute value. When a decorated property is set\n * the element will update and render. A {@linkcode PropertyDeclaration} may\n * optionally be supplied to configure property features.\n *\n * This decorator should only be used for public fields. As public fields,\n * properties should be considered as primarily settable by element users,\n * either via attribute or the property itself.\n *\n * Generally, properties that are changed by the element should be private or\n * protected fields and should use the {@linkcode state} decorator.\n *\n * However, sometimes element code does need to set a public property. This\n * should typically only be done in response to user interaction, and an event\n * should be fired informing the user; for example, a checkbox sets its\n * `checked` property when clicked and fires a `changed` event. Mutating public\n * properties should typically not be done for non-primitive (object or array)\n * properties. In other cases when an element needs to manage state, a private\n * property decorated via the {@linkcode state} decorator should be used. When\n * needed, state properties can be initialized via public properties to\n * facilitate complex interactions.\n *\n * ```ts\n * class MyElement {\n * @property({ type: Boolean })\n * clicked = false;\n * }\n * ```\n * @category Decorator\n * @ExportDecoratedItems\n */\nexport function property(options?: PropertyDeclaration) {\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n return (protoOrDescriptor: Object | ClassElement, name?: PropertyKey): any =>\n name !== undefined\n ? legacyProperty(options!, protoOrDescriptor as Object, name)\n : standardProperty(options!, protoOrDescriptor as ClassElement);\n}\n", "/**\n * @license\n * Copyright 2021 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/*\n * IMPORTANT: For compatibility with tsickle and the Closure JS compiler, all\n * property decorators (but not class decorators) in this file that have\n * an @ExportDecoratedItems annotation must be defined as a regular function,\n * not an arrow function.\n */\n\nimport {decorateProperty} from './base.js';\n\nimport type {ReactiveElement} from '../reactive-element.js';\nimport type {QueryAssignedNodesOptions} from './query-assigned-nodes.js';\n\nconst NODE_MODE = false;\nconst global = NODE_MODE ? globalThis : window;\n\n/**\n * A tiny module scoped polyfill for HTMLSlotElement.assignedElements.\n */\nconst slotAssignedElements =\n global.HTMLSlotElement?.prototype.assignedElements != null\n ? (slot: HTMLSlotElement, opts?: AssignedNodesOptions) =>\n slot.assignedElements(opts)\n : (slot: HTMLSlotElement, opts?: AssignedNodesOptions) =>\n slot\n .assignedNodes(opts)\n .filter(\n (node): node is Element => node.nodeType === Node.ELEMENT_NODE\n );\n\n/**\n * Options for the {@linkcode queryAssignedElements} decorator. Extends the\n * options that can be passed into\n * [HTMLSlotElement.assignedElements](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements).\n */\nexport interface QueryAssignedElementsOptions\n extends QueryAssignedNodesOptions {\n /**\n * CSS selector used to filter the elements returned. For example, a selector\n * of `\".item\"` will only include elements with the `item` class.\n */\n selector?: string;\n}\n\n/**\n * A property decorator that converts a class property into a getter that\n * returns the `assignedElements` of the given `slot`. Provides a declarative\n * way to use\n * [`HTMLSlotElement.assignedElements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements).\n *\n * Can be passed an optional {@linkcode QueryAssignedElementsOptions} object.\n *\n * Example usage:\n * ```ts\n * class MyElement {\n * @queryAssignedElements({ slot: 'list' })\n * listItems!: Array;\n * @queryAssignedElements()\n * unnamedSlotEls!: Array;\n *\n * render() {\n * return html`\n * `.\n *\n * @category Decorator\n */\nexport function queryAssignedElements(options?: QueryAssignedElementsOptions) {\n const {slot, selector} = options ?? {};\n return decorateProperty({\n descriptor: (_name: PropertyKey) => ({\n get(this: ReactiveElement) {\n const slotSelector = `slot${slot ? `[name=${slot}]` : ':not([name])'}`;\n const slotEl =\n this.renderRoot?.querySelector(slotSelector);\n const elements =\n slotEl != null ? slotAssignedElements(slotEl, options) : [];\n if (selector) {\n return elements.filter((node) => node.matches(selector));\n }\n return elements;\n },\n enumerable: true,\n configurable: true,\n }),\n });\n}\n", "/**\n * @license\n * Copyright 2019 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\nconst NODE_MODE = false;\nconst global = NODE_MODE ? globalThis : window;\n\n/**\n * Whether the current browser supports `adoptedStyleSheets`.\n */\nexport const supportsAdoptingStyleSheets: boolean =\n global.ShadowRoot &&\n (global.ShadyCSS === undefined || global.ShadyCSS.nativeShadow) &&\n 'adoptedStyleSheets' in Document.prototype &&\n 'replace' in CSSStyleSheet.prototype;\n\n/**\n * A CSSResult or native CSSStyleSheet.\n *\n * In browsers that support constructible CSS style sheets, CSSStyleSheet\n * object can be used for styling along side CSSResult from the `css`\n * template tag.\n */\nexport type CSSResultOrNative = CSSResult | CSSStyleSheet;\n\nexport type CSSResultArray = Array;\n\n/**\n * A single CSSResult, CSSStyleSheet, or an array or nested arrays of those.\n */\nexport type CSSResultGroup = CSSResultOrNative | CSSResultArray;\n\nconst constructionToken = Symbol();\n\nconst cssTagCache = new WeakMap();\n\n/**\n * A container for a string of CSS text, that may be used to create a CSSStyleSheet.\n *\n * CSSResult is the return value of `css`-tagged template literals and\n * `unsafeCSS()`. In order to ensure that CSSResults are only created via the\n * `css` tag and `unsafeCSS()`, CSSResult cannot be constructed directly.\n */\nexport class CSSResult {\n // This property needs to remain unminified.\n ['_$cssResult$'] = true;\n readonly cssText: string;\n private _styleSheet?: CSSStyleSheet;\n private _strings: TemplateStringsArray | undefined;\n\n private constructor(\n cssText: string,\n strings: TemplateStringsArray | undefined,\n safeToken: symbol\n ) {\n if (safeToken !== constructionToken) {\n throw new Error(\n 'CSSResult is not constructable. Use `unsafeCSS` or `css` instead.'\n );\n }\n this.cssText = cssText;\n this._strings = strings;\n }\n\n // This is a getter so that it's lazy. In practice, this means stylesheets\n // are not created until the first element instance is made.\n get styleSheet(): CSSStyleSheet | undefined {\n // If `supportsAdoptingStyleSheets` is true then we assume CSSStyleSheet is\n // constructable.\n let styleSheet = this._styleSheet;\n const strings = this._strings;\n if (supportsAdoptingStyleSheets && styleSheet === undefined) {\n const cacheable = strings !== undefined && strings.length === 1;\n if (cacheable) {\n styleSheet = cssTagCache.get(strings);\n }\n if (styleSheet === undefined) {\n (this._styleSheet = styleSheet = new CSSStyleSheet()).replaceSync(\n this.cssText\n );\n if (cacheable) {\n cssTagCache.set(strings, styleSheet);\n }\n }\n }\n return styleSheet;\n }\n\n toString(): string {\n return this.cssText;\n }\n}\n\ntype ConstructableCSSResult = CSSResult & {\n new (\n cssText: string,\n strings: TemplateStringsArray | undefined,\n safeToken: symbol\n ): CSSResult;\n};\n\nconst textFromCSSResult = (value: CSSResultGroup | number) => {\n // This property needs to remain unminified.\n if ((value as CSSResult)['_$cssResult$'] === true) {\n return (value as CSSResult).cssText;\n } else if (typeof value === 'number') {\n return value;\n } else {\n throw new Error(\n `Value passed to 'css' function must be a 'css' function result: ` +\n `${value}. Use 'unsafeCSS' to pass non-literal values, but take care ` +\n `to ensure page security.`\n );\n }\n};\n\n/**\n * Wrap a value for interpolation in a {@linkcode css} tagged template literal.\n *\n * This is unsafe because untrusted CSS text can be used to phone home\n * or exfiltrate data to an attacker controlled site. Take care to only use\n * this with trusted input.\n */\nexport const unsafeCSS = (value: unknown) =>\n new (CSSResult as ConstructableCSSResult)(\n typeof value === 'string' ? value : String(value),\n undefined,\n constructionToken\n );\n\n/**\n * A template literal tag which can be used with LitElement's\n * {@linkcode LitElement.styles} property to set element styles.\n *\n * For security reasons, only literal string values and number may be used in\n * embedded expressions. To incorporate non-literal values {@linkcode unsafeCSS}\n * may be used inside an expression.\n */\nexport const css = (\n strings: TemplateStringsArray,\n ...values: (CSSResultGroup | number)[]\n): CSSResult => {\n const cssText =\n strings.length === 1\n ? strings[0]\n : values.reduce(\n (acc, v, idx) => acc + textFromCSSResult(v) + strings[idx + 1],\n strings[0]\n );\n return new (CSSResult as ConstructableCSSResult)(\n cssText,\n strings,\n constructionToken\n );\n};\n\n/**\n * Applies the given styles to a `shadowRoot`. When Shadow DOM is\n * available but `adoptedStyleSheets` is not, styles are appended to the\n * `shadowRoot` to [mimic spec behavior](https://wicg.github.io/construct-stylesheets/#using-constructed-stylesheets).\n * Note, when shimming is used, any styles that are subsequently placed into\n * the shadowRoot should be placed *before* any shimmed adopted styles. This\n * will match spec behavior that gives adopted sheets precedence over styles in\n * shadowRoot.\n */\nexport const adoptStyles = (\n renderRoot: ShadowRoot,\n styles: Array\n) => {\n if (supportsAdoptingStyleSheets) {\n (renderRoot as ShadowRoot).adoptedStyleSheets = styles.map((s) =>\n s instanceof CSSStyleSheet ? s : s.styleSheet!\n );\n } else {\n styles.forEach((s) => {\n const style = document.createElement('style');\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n const nonce = (global as any)['litNonce'];\n if (nonce !== undefined) {\n style.setAttribute('nonce', nonce);\n }\n style.textContent = (s as CSSResult).cssText;\n renderRoot.appendChild(style);\n });\n }\n};\n\nconst cssResultFromStyleSheet = (sheet: CSSStyleSheet) => {\n let cssText = '';\n for (const rule of sheet.cssRules) {\n cssText += rule.cssText;\n }\n return unsafeCSS(cssText);\n};\n\nexport const getCompatibleStyle =\n supportsAdoptingStyleSheets ||\n (NODE_MODE && global.CSSStyleSheet === undefined)\n ? (s: CSSResultOrNative) => s\n : (s: CSSResultOrNative) =>\n s instanceof CSSStyleSheet ? cssResultFromStyleSheet(s) : s;\n", "/**\n * @license\n * Copyright 2017 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/**\n * Use this module if you want to create your own base class extending\n * {@link ReactiveElement}.\n * @packageDocumentation\n */\n\nimport {\n getCompatibleStyle,\n adoptStyles,\n CSSResultGroup,\n CSSResultOrNative,\n} from './css-tag.js';\nimport type {\n ReactiveController,\n ReactiveControllerHost,\n} from './reactive-controller.js';\n\n// In the Node build, this import will be injected by Rollup:\n// import {HTMLElement, customElements} from '@lit-labs/ssr-dom-shim';\n\nexport * from './css-tag.js';\nexport type {\n ReactiveController,\n ReactiveControllerHost,\n} from './reactive-controller.js';\n\nconst NODE_MODE = false;\nconst global = NODE_MODE ? globalThis : window;\n\nif (NODE_MODE) {\n global.customElements ??= customElements;\n}\n\nconst DEV_MODE = true;\n\nlet requestUpdateThenable: (name: string) => {\n then: (\n onfulfilled?: (value: boolean) => void,\n _onrejected?: () => void\n ) => void;\n};\n\nlet issueWarning: (code: string, warning: string) => void;\n\nconst trustedTypes = (global as unknown as {trustedTypes?: {emptyScript: ''}})\n .trustedTypes;\n\n// Temporary workaround for https://crbug.com/993268\n// Currently, any attribute starting with \"on\" is considered to be a\n// TrustedScript source. Such boolean attributes must be set to the equivalent\n// trusted emptyScript value.\nconst emptyStringForBooleanAttribute = trustedTypes\n ? (trustedTypes.emptyScript as unknown as '')\n : '';\n\nconst polyfillSupport = DEV_MODE\n ? global.reactiveElementPolyfillSupportDevMode\n : global.reactiveElementPolyfillSupport;\n\nif (DEV_MODE) {\n // Ensure warnings are issued only 1x, even if multiple versions of Lit\n // are loaded.\n const issuedWarnings: Set = (global.litIssuedWarnings ??=\n new Set());\n\n // Issue a warning, if we haven't already.\n issueWarning = (code: string, warning: string) => {\n warning += ` See https://lit.dev/msg/${code} for more information.`;\n if (!issuedWarnings.has(warning)) {\n console.warn(warning);\n issuedWarnings.add(warning);\n }\n };\n\n issueWarning(\n 'dev-mode',\n `Lit is in dev mode. Not recommended for production!`\n );\n\n // Issue polyfill support warning.\n if (global.ShadyDOM?.inUse && polyfillSupport === undefined) {\n issueWarning(\n 'polyfill-support-missing',\n `Shadow DOM is being polyfilled via \\`ShadyDOM\\` but ` +\n `the \\`polyfill-support\\` module has not been loaded.`\n );\n }\n\n requestUpdateThenable = (name) => ({\n then: (\n onfulfilled?: (value: boolean) => void,\n _onrejected?: () => void\n ) => {\n issueWarning(\n 'request-update-promise',\n `The \\`requestUpdate\\` method should no longer return a Promise but ` +\n `does so on \\`${name}\\`. Use \\`updateComplete\\` instead.`\n );\n if (onfulfilled !== undefined) {\n onfulfilled(false);\n }\n },\n });\n}\n\n/**\n * Contains types that are part of the unstable debug API.\n *\n * Everything in this API is not stable and may change or be removed in the future,\n * even on patch releases.\n */\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport namespace ReactiveUnstable {\n /**\n * When Lit is running in dev mode and `window.emitLitDebugLogEvents` is true,\n * we will emit 'lit-debug' events to window, with live details about the update and render\n * lifecycle. These can be useful for writing debug tooling and visualizations.\n *\n * Please be aware that running with window.emitLitDebugLogEvents has performance overhead,\n * making certain operations that are normally very cheap (like a no-op render) much slower,\n * because we must copy data and dispatch events.\n */\n // eslint-disable-next-line @typescript-eslint/no-namespace\n export namespace DebugLog {\n export type Entry = Update;\n export interface Update {\n kind: 'update';\n }\n }\n}\n\ninterface DebugLoggingWindow {\n // Even in dev mode, we generally don't want to emit these events, as that's\n // another level of cost, so only emit them when DEV_MODE is true _and_ when\n // window.emitLitDebugEvents is true.\n emitLitDebugLogEvents?: boolean;\n}\n\n/**\n * Useful for visualizing and logging insights into what the Lit template system is doing.\n *\n * Compiled out of prod mode builds.\n */\nconst debugLogEvent = DEV_MODE\n ? (event: ReactiveUnstable.DebugLog.Entry) => {\n const shouldEmit = (global as unknown as DebugLoggingWindow)\n .emitLitDebugLogEvents;\n if (!shouldEmit) {\n return;\n }\n global.dispatchEvent(\n new CustomEvent('lit-debug', {\n detail: event,\n })\n );\n }\n : undefined;\n\n/*\n * When using Closure Compiler, JSCompiler_renameProperty(property, object) is\n * replaced at compile time by the munged name for object[property]. We cannot\n * alias this function, so we have to use a small shim that has the same\n * behavior when not compiling.\n */\n/*@__INLINE__*/\nconst JSCompiler_renameProperty =
(\n prop: P,\n _obj: unknown\n): P => prop;\n\n/**\n * Converts property values to and from attribute values.\n */\nexport interface ComplexAttributeConverter