Merge pull request #48 from thuydotm/layouts_docs

Layouts - update docs

pixi.toml

@@ -44,7 +44,7 @@ _install-ui = 'playwright install chromium'
 
 [feature.test-ui.tasks.test-ui]
 cmd = 'pytest ./tests/ui --ui --browser chromium -n logical --dist loadgroup --reruns 3 --reruns-delay 10'
-depends_on = ["_install-ui"]
+depends-on = ["_install-ui"]
 
 [feature.build.dependencies]
 python-build = "*"

src/panel_material_ui/layout/base.py

@@ -27,6 +27,16 @@ class MaterialNamedListLike(MaterialComponent, NamedListLike):
 
 
 class Paper(MaterialListLike):
+    """
+    Paper implements a container for displaying content on an elevated surface.
+
+    Reference to the equivalent Material UI Paper component:
+    https://mui.com/material-ui/react-paper/
+
+    :Example:
+    >>> Paper(name="Paper", objects=[1, 2, 3], elevation=10, width=200, height=200)
+    """
+
     elevation = param.Integer(default=1, bounds=(0, None))
 
     _esm = "Paper.jsx"
@@ -37,14 +47,24 @@ class Card(MaterialListLike):
     A `Card` layout allows arranging multiple panel objects in a
     collapsible, vertical container with a header bar.
 
-    Reference: https://panel.holoviz.org/reference/layouts/Card.html
+    Some missing features (if any) when comparing with the corresponding
+    Panel Card layout [panel.Card](https://panel.holoviz.org/reference/layouts/Card.html):
+    - active_header_background
+    - auto_scroll_limit
+    - button_css_classes
+    - header_background
+    - header_color
+    - header_css_classes
+    - hide_header
+    - scroll
+    - scroll_button_threshold
+    - scroll_position
+    - title_css_classes
+    - view_latest
 
     :Example:
 
-    >>> Card(
-    ...   some_widget, some_pane, some_python_object,
-    ...   title='Card', styles=dict(background='WhiteSmoke'),
-    ... )
+    >>> Card(some_widget, some_pane, some_python_object, title='Card')
     """
 
     collapsed = param.Boolean(
@@ -88,6 +108,26 @@ def select(self, selector: type | Callable[[Viewable], bool] | None = None) -> l
 
 
 class Accordion(MaterialNamedListLike):
+    """
+    The `Accordion` layout is a type of `Card` layout that allows switching
+    between multiple objects by clicking on the corresponding card header.
+
+    The labels for each card will default to the `name` parameter of the card’s
+    contents, but may also be defined explicitly as part of a tuple.
+
+    `Accordion` has a list-like API that allows
+    interactively updating and modifying the cards using the methods `append`,
+    `extend`, `clear`, `insert`, `pop`, `remove` and `__setitem__`.
+
+    Missing features (if any) when comparing with the corresponding
+    Panel Accordion layout [panel.Accordion](https://panel.holoviz.org/reference/layouts/Accordion.html):
+    `active_header_background`, `header_background`, `header_color`, `scroll`
+
+    :Example:
+
+    >>> Accordion(("Card 1", "Card 1 objects"), ("Card 2", "Card 2 objects"))
+    """
+
     active = param.List(
         default=[],
         doc="""
@@ -111,6 +151,26 @@ def __init__(self, *objects, **params):
 
 
 class Tabs(MaterialNamedListLike):
+    """
+    The `Tabs` layout allows switching between multiple objects by clicking
+    on the corresponding tab header.
+
+    Tab labels may be defined explicitly as part of a tuple or will be
+    inferred from the `name` parameter of the tab’s contents.
+
+    Like `Accordion`, `Tabs` has a list-like API with methods to
+    `append`, `extend`, `clear`, `insert`, `pop`, `remove` and `__setitem__`,
+    which make it possible to interactively update and modify the tabs.
+
+    Missing features (if any) when comparing with the corresponding
+    Panel Tabs layout [panel.Tabs](https://panel.holoviz.org/reference/layouts/Tabs.html):
+    `closable`, `scroll`.
+
+    :Example:
+
+    >>> Tabs(("Tab 1", "Tab 1 objects"), ("Tab 2", "Card 2 objects"))
+
+    """
     active = param.Integer(
         default=0,
         bounds=(0, None),
@@ -157,6 +217,17 @@ def _get_child_model(self, child, doc, root, parent, comm):
 
 
 class Divider(MaterialListLike):
+    """
+    A `Divider` draws a horizontal rule (a `<hr>` tag in HTML) to separate
+    multiple components in a layout.
+
+    Reference to the equivalent Panel Divider layout:
+    https://panel.holoviz.org/reference/layouts/Divider.html
+
+    :Example:
+
+    >>> Divider(sizing_mode="stretch_width")
+    """
 
     orientation = param.Selector(default="horizontal", objects=["horizontal", "vertical"])
 
@@ -183,13 +254,41 @@ class Alert(MaterialListLike):
 
 
 class Backdrop(MaterialListLike):
+    """
+    The `Backdrop` component can be used to create a semi-transparent overlay over the application's UI.
+    It is often used to focus attention on a specific part of the interface,
+    such as during loading states or while a modal dialog is open.
+
+    Reference to the corresponding Material UI `Backdrop`:
+    https://mui.com/material-ui/react-backdrop/
+
+    Example:
+    >>> close = Button(on_click=lambda _: backdrop.param.update(open=False), label='Close')  # type: ignore
+    >>> backdrop = Backdrop(LoadingIndicator(), close)
+    >>> button = Button(on_click=lambda _: backdrop.param.update(open=True), label=f'Open {Backdrop.name}')
+    >>> pn.Column(button, backdrop).servable()
+    """
 
     open = param.Boolean(default=False)
 
     _esm = "Backdrop.jsx"
 
 
 class Dialog(MaterialListLike):
+    """
+    The `Dialog` can be used to display important content in a modal-like overlay that requires
+    user interaction. It is often used for tasks such as confirmations, forms, or displaying
+    additional information.
+
+    Reference to the corresponding Material UI `Dialog`:
+    https://mui.com/material-ui/react-dialog/
+
+    Example:
+    >>> close = Button(on_click=lambda _: dialog.param.update(open=False), label='Close')  # type: ignore
+    >>> dialog = Dialog("This is a modal", close)
+    >>> button = Button(on_click=lambda _: dialog.param.update(open=True), label=f'Open {Dialog.name}')
+    >>> pn.Column(button, dialog).servable()
+    """
 
     full_screen = param.Boolean(default=False)