Implement docked variant for Drawer (#696)

Author: philippjfr

examples/reference/layouts/Drawer.ipynb

@@ -17,24 +17,7 @@
    "cell_type": "markdown",
    "id": "a6c6a705-0ea1-4a19-a264-eacac2b2544e",
    "metadata": {},
-   "source": [
-    "The `Drawer` component (akin to a sidebar) provides ergonomic access to destinations in a site or app functionality.\n",
-    "\n",
-    "## Parameters:\n",
-    "For details on other options for customizing the component see the layout and styling how-to guides.\n",
-    "\n",
-    "### Core\n",
-    "\n",
-    "* **`open`** (`boolean`): Whether the `Drawer` is open.\n",
-    "\n",
-    "### Display\n",
-    "\n",
-    "* **`anchor`** (`Literal[\"left\", \"right\", \"bottom\", \"right\"]`): Where to position the `Drawer`.\n",
-    "* **`size`** (`int`): The width or height depending on whether the `Drawer` is rendered on the left/right or top/bottom respectively.\n",
-    "* **`variant`** (`Literal[\"temporary\", \"persistent\", \"permanent\"]`): Whether the Drawer is temporary, persistent or permanent.\n",
-    "\n",
-    "---"
-   ]
+   "source": "The `Drawer` component (akin to a sidebar) provides ergonomic access to destinations in a site or app functionality.\n\n## Parameters:\nFor details on other options for customizing the component see the layout and styling how-to guides.\n\n### Core\n\n* **`open`** (`boolean`): Whether the `Drawer` is open.\n\n### Display\n\n* **`anchor`** (`Literal[\"left\", \"right\", \"bottom\", \"top\"]`): Where to position the `Drawer`.\n* **`dock_position`** (`Literal[\"start\", \"middle\", \"end\"]`): Position of the toggle tab along the drawer edge (only applies to 'docked' variant).\n* **`size`** (`int`): The width or height depending on whether the `Drawer` is rendered on the left/right or top/bottom respectively.\n* **`variant`** (`Literal[\"temporary\", \"persistent\", \"permanent\", \"docked\"]`): Whether the Drawer is temporary, persistent, permanent or docked.\n\n---"
   },
   {
    "cell_type": "markdown",
@@ -140,6 +123,20 @@
     ").preview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cbad6d15",
+   "source": "### Docked drawer\n\nA docked drawer renders a small toggle tab on the edge where it's anchored, allowing users to open and close it without needing a separate button. When closed, only the tab is visible; when open, the drawer slides out with the tab attached to close it again.\n\nUse `dock_position` to control where the tab appears along the drawer edge (`\"start\"`, `\"middle\"`, or `\"end\"`):",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "c6356ab8",
+   "source": "drawer = Drawer(\n    \"## Navigation\",\n    Button(label=\"Home\"),\n    Button(label=\"Settings\"),\n    size=250,\n    variant=\"docked\",\n    anchor=\"left\",\n    dock_position=\"middle\",\n)\n\nRow(drawer, Container(\"# Main Content\", width_option='sm')).preview()",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
   {
    "cell_type": "code",
    "execution_count": null,

src/panel_material_ui/layout/Drawer.jsx

@@ -1,23 +1,109 @@
 import Drawer from "@mui/material/Drawer"
+import Icon from "@mui/material/Icon"
+import Paper from "@mui/material/Paper"
 import {apply_flex} from "./utils"
 
+const TAB_SIZE = 24
+const TAB_LENGTH = 48
+
+const anchorToChevron = {
+  left: {open: "chevron_left", closed: "chevron_right"},
+  right: {open: "chevron_right", closed: "chevron_left"},
+  top: {open: "expand_less", closed: "expand_more"},
+  bottom: {open: "expand_more", closed: "expand_less"},
+}
+
+function getPositionStyle(anchor, dockPosition) {
+  const isHorizontal = anchor === "left" || anchor === "right"
+  if (isHorizontal) {
+    switch (dockPosition) {
+      case "start": return {top: `${TAB_LENGTH}px`}
+      case "end": return {bottom: `${TAB_LENGTH}px`}
+      default: return {top: "50%", transform: "translateY(-50%)"}
+    }
+  } else {
+    switch (dockPosition) {
+      case "start": return {left: `${TAB_LENGTH}px`}
+      case "end": return {right: `${TAB_LENGTH}px`}
+      default: return {left: "50%", transform: "translateX(-50%)"}
+    }
+  }
+}
+
+function DockedTab({anchor, open, dockPosition, attached, onClick}) {
+  const isHorizontal = anchor === "left" || anchor === "right"
+  const icon = anchorToChevron[anchor][open ? "open" : "closed"]
+
+  const positionStyles = (() => {
+    if (attached) {
+      const offsetSide = anchor === "left" ? "right" : anchor === "right" ? "left" : anchor === "top" ? "bottom" : "top"
+      return {
+        [offsetSide]: `-${TAB_SIZE + 1}px`,
+        ...getPositionStyle(anchor, dockPosition),
+      }
+    }
+    return {
+      [anchor]: 0,
+      ...getPositionStyle(anchor, dockPosition),
+    }
+  })()
+
+  const tabStyle = {
+    position: "absolute",
+    ...positionStyles,
+    width: isHorizontal ? `${TAB_SIZE}px` : `${TAB_LENGTH}px`,
+    height: isHorizontal ? `${TAB_LENGTH}px` : `${TAB_SIZE}px`,
+    minWidth: 0,
+    minHeight: 0,
+    padding: 0,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    cursor: "pointer",
+    zIndex: 1,
+    borderRadius: (() => {
+      switch (anchor) {
+        case "left": return "0 4px 4px 0"
+        case "right": return "4px 0 0 4px"
+        case "top": return "0 0 4px 4px"
+        case "bottom": return "4px 4px 0 0"
+      }
+    })(),
+  }
+
+  return (
+    <Paper
+      elevation={2}
+      sx={tabStyle}
+      onClick={onClick}
+      role="button"
+      aria-label={open ? "Close drawer" : "Open drawer"}
+    >
+      <Icon sx={{fontSize: "1.2rem"}}>{icon}</Icon>
+    </Paper>
+  )
+}
+
 export function render({model, view}) {
   const [anchor] = model.useState("anchor")
+  const [dockPosition] = model.useState("dock_position")
   const [open, setOpen] = model.useState("open")
   const [size] = model.useState("size")
   const [sx] = model.useState("sx")
   const [variant] = model.useState("variant")
   const objects = model.get_child("objects")
 
+  const isDocked = variant === "docked"
+
   let dims
   if (!["top", "bottom"].includes(anchor)) {
     dims = {width: `${size}px`}
-    if (variant !== "temporary") {
+    if (!["temporary", "docked"].includes(variant)) {
       view.el.style.width = `${open ? size : 0}px`
     }
   } else {
     dims = {height: `${size}px`}
-    if (variant !== "temporary") {
+    if (!["temporary", "docked"].includes(variant)) {
       view.el.style.height = `${open ? size : 0}px`
     }
   }
@@ -32,6 +118,49 @@ export function render({model, view}) {
     return () => model.off("lifecycle:update_layout", handler)
   }, [])
 
+  if (isDocked) {
+    const isHorizontal = anchor === "left" || anchor === "right"
+    const containerStyle = {
+      position: "fixed",
+      top: 0,
+      [anchor]: 0,
+      [isHorizontal ? "width" : "height"]: open ? `${size + TAB_SIZE}px` : `${TAB_SIZE}px`,
+      [isHorizontal ? "height" : "width"]: "100%",
+      zIndex: 1200,
+      pointerEvents: "none",
+    }
+
+    const innerStyle = {
+      position: "relative",
+      [isHorizontal ? "width" : "height"]: "100%",
+      [isHorizontal ? "height" : "width"]: "100%",
+      pointerEvents: "auto",
+    }
+
+    return (
+      <div style={containerStyle}>
+        <div style={innerStyle}>
+          <Drawer
+            anchor={anchor}
+            open={open}
+            onClose={() => setOpen(false)}
+            slotProps={{paper: {sx: [dims, {overflow: "visible"}, sx || {}]}}}
+            variant="persistent"
+          >
+            {objects.map((object, index) => {
+              apply_flex(view.get_child_view(model.objects[index]), "column")
+              return object
+            })}
+            <DockedTab anchor={anchor} open={open} dockPosition={dockPosition} attached onClick={() => setOpen(false)} />
+          </Drawer>
+          {!open && (
+            <DockedTab anchor={anchor} open={false} dockPosition={dockPosition} attached={false} onClick={() => setOpen(true)} />
+          )}
+        </div>
+      </div>
+    )
+  }
+
   return (
     <Drawer anchor={anchor} open={open} onClose={() => setOpen(false)} slotProps={{paper: {sx: [dims, sx || {}]}}} variant={variant}>
       {objects.map((object, index) => {

src/panel_material_ui/layout/base.py

@@ -1108,21 +1108,25 @@ class Drawer(MaterialListLike):
         default="left", objects=["left", "right", "top", "bottom"],
         doc="Anchor position for the drawer.")  # type: ignore[assignment]
 
+    dock_position: t.Literal["start", "middle", "end"] = param.Selector(
+        default="middle", objects=["start", "middle", "end"],
+        doc="Position of the toggle tab along the drawer edge (only applies to 'docked' variant).")  # type: ignore[assignment]
+
     size = param.Integer(default=250, doc="""
         The width (for left/right anchors) or height (for top/bottom anchors) of the drawer.""")
 
     open = param.Boolean(default=False, doc="""
         Whether the drawer is open.""")
 
-    variant: t.Literal["permanent", "persistent", "temporary"] = param.Selector(
-        default="temporary", objects=["permanent", "persistent", "temporary"],
+    variant: t.Literal["docked", "permanent", "persistent", "temporary"] = param.Selector(
+        default="temporary", objects=["docked", "permanent", "persistent", "temporary"],
         doc="Variant style of the drawer.")  # type: ignore[assignment]
 
     _esm_base = "Drawer.jsx"
 
     @param.depends("variant", watch=True, on_init=True)
     def _force_zero_dimensions(self):
-        if self.variant == "temporary":
+        if self.variant in ("temporary", "docked"):
             self.param.update(width=0, height=0, sizing_mode="fixed")
 
     def create_toggle(