Add main_width and app_bar_width to Page (#684)

* widths

* by breakpoint

Author: ahuang11

src/panel_material_ui/template/Page.jsx

@@ -51,6 +51,22 @@ const PAGE_DRAWER_RESIZE_HANDLE_SX = {
   }
 }
 
+// Normalize a width value into an MUI sx `maxWidth`.
+// Accepts a number (interpreted as pixels), a CSS length string
+// (e.g. "70ch", "60rem", "90%"), or a breakpoint dict
+// (e.g. {xs: "100%", md: 720, lg: 960}) which maps to a responsive sx object
+// where each value applies at that breakpoint and up. Returns undefined when unset.
+const to_css_width = (v) => (typeof v === "number" ? `${v}px` : v)
+const to_max_width = (v) => {
+  if (v == null) { return undefined }
+  if (typeof v === "object") {
+    return Object.fromEntries(
+      Object.entries(v).map(([bp, w]) => [bp, to_css_width(w)])
+    )
+  }
+  return to_css_width(v)
+}
+
 const Main = styled("main", {shouldForwardProp: (prop) => !["open", "variant", "sidebar_width", "contextbar_open", "context_variant", "contextbar_width"].includes(prop)})(
   ({sidebar_width, contextbar_width, theme, open, variant, contextbar_open, context_variant}) => {
     return ({
@@ -101,6 +117,8 @@ export function render({model, view}) {
   const [contextbar_resizable] = model.useState("contextbar_resizable")
   const [contextbar_variant] = model.useState("contextbar_variant")
   const [contextbar_width, setContextbarWidth] = model.useState("contextbar_width")
+  const [main_width] = model.useState("main_width")
+  const [app_bar_width] = model.useState("app_bar_width")
   const [dark_theme, setDarkTheme] = model.useState("dark_theme")
   const [logo] = model.useState("logo")
   const [open, setOpen] = model.useState("sidebar_open")
@@ -426,11 +444,30 @@ export function render({model, view}) {
     [primary_color]
   )
   const appBarSx = React.useMemo(() => [PAGE_APPBAR_SX, header_sx], [header_sx])
+  const appBarToolbarSx = React.useMemo(() => {
+    // app_bar_width follows main_width when unset, so the header stays aligned
+    // with the clamped main content; an explicit app_bar_width overrides it.
+    const maxWidth = to_max_width(app_bar_width ?? main_width)
+    return maxWidth == null ? undefined : {maxWidth, width: "100%", alignSelf: "center"}
+  }, [app_bar_width, main_width])
+  const mainContentSx = React.useMemo(() => {
+    const maxWidth = to_max_width(main_width)
+    return {
+      flexGrow: 1,
+      display: "flex",
+      minHeight: 0,
+      flexDirection: "column",
+      overflowY: main_stretch ? "hidden" : "auto",
+      // alignSelf centers the clamped content within the (column) flex parent;
+      // margin:auto would compute to resolved pixels and is harder to assert on.
+      ...(maxWidth == null ? {} : {maxWidth, width: "100%", alignSelf: "center"}),
+    }
+  }, [main_stretch, main_width])
 
   return (
     <Box className={`mui-${color_scheme}`} sx={pageRootSx}>
       <AppBar position="fixed" color="primary" className="header" sx={appBarSx}>
-        <Toolbar>
+        <Toolbar sx={appBarToolbarSx}>
           {(model.sidebar.length > 0 && drawer_variant !== "permanent") &&
             <Tooltip enterDelay={500} title={open ? "Close drawer" : "Open drawer"}>
               <IconButton
@@ -534,7 +571,7 @@ export function render({model, view}) {
           <Toolbar sx={toolbarSx}>
             <Typography variant="h5">&nbsp;</Typography>
           </Toolbar>
-          <Box sx={{flexGrow: 1, display: "flex", minHeight: 0, flexDirection: "column", overflowY: main_stretch ? "hidden" : "auto"}}>
+          <Box className="main-content" sx={mainContentSx}>
             {main.map((object, index) => {
               apply_flex(view.get_child_view(model.main[index]), "column")
               return object

src/panel_material_ui/template/base.py

@@ -71,6 +71,16 @@ class Page(MaterialComponent, ResourceComponent):
     >>> Page(main=['# Content'], title='My App')
     """
 
+    app_bar_width = param.ClassSelector(default=None, class_=(int, str, dict), doc="""
+        Maximum width of the app bar (header) content. When set, the toolbar
+        content is clamped to this width and centered, aligning it with a
+        clamped main area. Accepts a number (interpreted as pixels), a CSS
+        length string (e.g. '70ch', '60rem', '90%'), or a dict mapping Material
+        UI breakpoints to widths (e.g. {'xs': '100%', 'md': 720, 'lg': 960}),
+        where each value applies at that breakpoint and up. Defaults to None
+        (full width); when unset it follows ``main_width`` so the header stays
+        aligned with the main content.""")
+
     busy = param.Boolean(default=False, readonly=True, doc="Whether the page is busy.")
 
     busy_indicator: t.Literal["circular", "linear"] | None = param.Selector(default="linear", objects=["circular", "linear", None], doc="""
@@ -100,6 +110,14 @@ class Page(MaterialComponent, ResourceComponent):
 
     main = Children(doc="Items rendered in the main area.")
 
+    main_width = param.ClassSelector(default=None, class_=(int, str, dict), doc="""
+        Maximum width of the main content area. When set, the main content is
+        clamped to this width and centered to improve readability. Accepts a
+        number (interpreted as pixels), a CSS length string (e.g. '70ch',
+        '60rem', '90%'), or a dict mapping Material UI breakpoints to widths
+        (e.g. {'xs': '100%', 'md': 720, 'lg': 960}), where each value applies
+        at that breakpoint and up. Defaults to None (full width).""")
+
     meta = param.ClassSelector(default=None, class_=Meta, doc="Meta tags and other HTML head elements.")
 
     logo = param.ClassSelector(default=None, class_=(str, pathlib.Path, dict), doc="""

tests/ui/template/test_page.py

@@ -188,6 +188,102 @@ def test_page_sidebar_width_persistence(page):
     expect(sidebar_paper).to_have_css("width", "450px")
 
 
+def test_page_main_width_default_unclamped(page):
+    """By default the main content area is not clamped (no max-width)."""
+    pg = Page(main=[pn.pane.Markdown("# Content")])
+
+    serve_component(page, pg)
+
+    main_content = page.locator(".main-content")
+    expect(main_content).to_be_attached()
+    expect(main_content).to_have_css("max-width", "none")
+
+
+def test_page_main_width_custom(page):
+    """main_width clamps and centers the main content area."""
+    pg = Page(main=[pn.pane.Markdown("# Content")], main_width=800)
+
+    serve_component(page, pg)
+
+    main_content = page.locator(".main-content")
+    expect(main_content).to_have_css("max-width", "800px")
+    # Centered via alignSelf in the column flex parent (margin:auto would
+    # compute to resolved pixels, so we assert on align-self instead).
+    expect(main_content).to_have_css("align-self", "center")
+
+
+def test_page_app_bar_width_default_unclamped(page):
+    """By default the app bar toolbar is not clamped (no max-width)."""
+    pg = Page(main=[pn.pane.Markdown("# Content")])
+
+    serve_component(page, pg)
+
+    toolbar = page.locator(".header .MuiToolbar-root")
+    expect(toolbar).to_have_css("max-width", "none")
+
+
+def test_page_app_bar_width_custom(page):
+    """app_bar_width clamps and centers the app bar toolbar content."""
+    pg = Page(main=[pn.pane.Markdown("# Content")], app_bar_width=900)
+
+    serve_component(page, pg)
+
+    toolbar = page.locator(".header .MuiToolbar-root")
+    expect(toolbar).to_have_css("max-width", "900px")
+    expect(toolbar).to_have_css("align-self", "center")
+
+
+def test_page_main_width_css_string(page):
+    """main_width accepts a CSS length string (resolved by the browser)."""
+    # 60rem resolves to 960px at the default 16px root font size.
+    pg = Page(main=[pn.pane.Markdown("# Content")], main_width="60rem")
+
+    serve_component(page, pg)
+
+    main_content = page.locator(".main-content")
+    expect(main_content).to_have_css("max-width", "960px")
+    expect(main_content).to_have_css("align-self", "center")
+
+
+def test_page_main_width_breakpoint_dict(page):
+    """main_width accepts a breakpoint dict, applying per-breakpoint clamps."""
+    pg = Page(main=[pn.pane.Markdown("# Content")], main_width={"xs": "100%", "md": 800})
+
+    serve_component(page, pg)
+
+    main_content = page.locator(".main-content")
+    # At/above the md breakpoint the 800px clamp applies.
+    page.set_viewport_size({"width": 1200, "height": 800})
+    expect(main_content).to_have_css("max-width", "800px")
+    # Below md the clamp falls back to the xs entry (100%), i.e. not 800px.
+    page.set_viewport_size({"width": 500, "height": 800})
+    expect(main_content).not_to_have_css("max-width", "800px")
+
+
+def test_page_app_bar_width_follows_main_width(page):
+    """When app_bar_width is unset, the toolbar follows main_width so the
+    header stays aligned with the clamped main content."""
+    pg = Page(main=[pn.pane.Markdown("# Content")], main_width=800)
+
+    serve_component(page, pg)
+
+    toolbar = page.locator(".header .MuiToolbar-root")
+    expect(toolbar).to_have_css("max-width", "800px")
+    expect(toolbar).to_have_css("align-self", "center")
+
+
+def test_page_app_bar_width_overrides_main_width(page):
+    """An explicit app_bar_width takes precedence over main_width for the toolbar."""
+    pg = Page(main=[pn.pane.Markdown("# Content")], main_width=800, app_bar_width=1200)
+
+    serve_component(page, pg)
+
+    toolbar = page.locator(".header .MuiToolbar-root")
+    expect(toolbar).to_have_css("max-width", "1200px")
+    main_content = page.locator(".main-content")
+    expect(main_content).to_have_css("max-width", "800px")
+
+
 def test_page_linear_progress_hidden_when_idle(page):
     """Test that linear progress bar is hidden (opacity: 0) when not busy."""
     pg = Page(