#308 improve page layout elements with documentation, more parameters and derive them from ValueElement

nicegui/page_layout.py

@@ -1,24 +1,53 @@
+from typing_extensions import Literal
+
 from . import globals
 from .element import Element
+from .elements.mixins.value_element import ValueElement
+
+DrawerSides = Literal['left', 'right']
+
+PageStickyPositions = Literal[
+    'top-right',
+    'top-left',
+    'bottom-right',
+    'bottom-left',
+    'top',
+    'right',
+    'bottom',
+    'left',
+]
 
 
-class Header(Element):
+class Header(ValueElement):
 
-    def __init__(self, fixed: bool = True) -> None:
+    def __init__(self, *, value: bool = True, fixed: bool = True) -> None:
+        '''Header
+
+        :param value: whether the header is already opened (default: `True`)
+        :param fixed: whether the header should be fixed to the top of the page (default: `True`)
+        '''
         with globals.get_client().layout:
-            super().__init__('q-header')
+            super().__init__(tag='q-header', value=value, on_value_change=None)
         self.classes('q-pa-md row items-start gap-4')
         code = list(self.client.layout._props['view'])
         code[1] = 'H' if fixed else 'h'
         self.client.layout._props['view'] = ''.join(code)
 
 
-class Drawer(Element):
+class Drawer(ValueElement):
+
+    def __init__(self, side: DrawerSides, *,
+                 value: bool = True, fixed: bool = True, top_corner: bool = False, bottom_corner: bool = False) -> None:
+        '''Drawer
 
-    def __init__(self, side: str, *, fixed: bool = True, top_corner: bool = False, bottom_corner: bool = False) -> None:
-        assert side in {'left', 'right'}
+        :param side: side of the page where the drawer should be placed (`left` or `right`)
+        :param value: whether the drawer is already opened (default: `True`)
+        :param fixed: whether the drawer is fixed or scrolls with the content (default: `True`)
+        :param top_corner: whether the drawer expands into the top corner (default: `False`)
+        :param bottom_corner: whether the drawer expands into the bottom corner (default: `False`)
+        '''
         with globals.get_client().layout:
-            super().__init__('q-drawer')
+            super().__init__(tag='q-drawer', value=value, on_value_change=None)
         self._props['show-if-above'] = True
         self._props['side'] = side
         self._classes = ['q-pa-md']
@@ -31,21 +60,42 @@ class Drawer(Element):
 
 class LeftDrawer(Drawer):
 
-    def __init__(self, fixed: bool = True, top_corner: bool = False, bottom_corner: bool = False) -> None:
-        super().__init__('left', fixed=fixed, top_corner=top_corner, bottom_corner=bottom_corner)
+    def __init__(self, *,
+                 value: bool = True, fixed: bool = True, top_corner: bool = False, bottom_corner: bool = False) -> None:
+        '''Left drawer
+
+        :param value: whether the drawer is already opened (default: `True`)
+        :param fixed: whether the drawer is fixed or scrolls with the content (default: `True`)
+        :param top_corner: whether the drawer expands into the top corner (default: `False`)
+        :param bottom_corner: whether the drawer expands into the bottom corner (default: `False`)
+        '''
+        super().__init__('left', value=value, fixed=fixed, top_corner=top_corner, bottom_corner=bottom_corner)
 
 
 class RightDrawer(Drawer):
 
-    def __init__(self, fixed: bool = True, top_corner: bool = False, bottom_corner: bool = False) -> None:
-        super().__init__('right', fixed=fixed, top_corner=top_corner, bottom_corner=bottom_corner)
+    def __init__(self, *,
+                 value: bool = True, fixed: bool = True, top_corner: bool = False, bottom_corner: bool = False) -> None:
+        '''Right drawer
+
+        :param value: whether the drawer is already opened (default: `True`)
+        :param fixed: whether the drawer is fixed or scrolls with the content (default: `True`)
+        :param top_corner: whether the drawer expands into the top corner (default: `False`)
+        :param bottom_corner: whether the drawer expands into the bottom corner (default: `False`)
+        '''
+        super().__init__('right', value=value, fixed=fixed, top_corner=top_corner, bottom_corner=bottom_corner)
+
 
+class Footer(ValueElement):
 
-class Footer(Element):
+    def __init__(self, *, value: bool = True, fixed: bool = True) -> None:
+        '''Footer
 
-    def __init__(self, fixed: bool = True) -> None:
+        :param value: whether the footer is already opened (default: `True`)
+        :param fixed: whether the footer is fixed or scrolls with the content (default: `True`)
+        '''
         with globals.get_client().layout:
-            super().__init__('q-footer')
+            super().__init__(tag='q-footer', value=value, on_value_change=None)
         self.classes('q-pa-md row items-start gap-4')
         code = list(self.client.layout._props['view'])
         code[9] = 'F' if fixed else 'f'
@@ -54,5 +104,15 @@ class Footer(Element):
 
 class PageSticky(Element):
 
-    def __init__(self) -> None:
+    def __init__(self, position: PageStickyPositions = 'bottom-right', x_offset: float = 0, y_offset: float = 0) -> None:
+        '''Page sticky
+
+        A sticky element that is always visible at the bottom of the page.
+
+        :param position: position of the sticky element (default: `'bottom-right'`)
+        :param x_offset: horizontal offset of the sticky element (default: `0`)
+        :param y_offset: vertical offset of the sticky element (default: `0`)
+        '''
         super().__init__('q-page-sticky')
+        self._props['position'] = position
+        self._props['offset'] = [x_offset, y_offset]