contain-css-svelte 1.2.3 → 1.3.0

package/dist/layout/Sidebar.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">import { elementProps } from "../util";
 import { COLOR_VARS, TYPOGRAPHY_VARS, } from "../styleProps";
-let { left, right, children, expandLabel = "Expand sidebar", collapseLabel = "Collapse sidebar", class: className, ...restProps } = $props();
+let { left, right, children, overlay = false, open = $bindable(undefined), expandLabel = "Expand sidebar", collapseLabel = "Collapse sidebar", class: className, ...restProps } = $props();
 /* The shorthands sidebar's own CSS backs, one group per mixin it
    includes. The Props type is derived from this same array, so what the
    component accepts and what it emits cannot drift apart. */
@@ -12,14 +12,22 @@ const el = $derived(elementProps(restProps, "sidebar", [
     ...SIDEBAR_VARS,
     "width",
 ]));
-let expandedHamburger = $state(false);
-let expandedBar = $state(true);
+/* One piece of state, two layouts. The wide rail and the compact sheet
+   disagree about what "untouched" should look like -- the rail starts open,
+   the sheet starts closed -- so `undefined` stands for "this layout's
+   default" and each layout resolves it its own way. The moment anything
+   (either built-in toggle, or a caller through `bind:open`) writes a
+   boolean, both layouts read that same boolean, which is what keeps
+   programmatic control and the internal toggles in sync. */
+const expandedBar = $derived(open ?? true);
+const expandedHamburger = $derived(open ?? false);
 </script>
 
 <aside
   class={["sidebar", className]}
   class:right
   class:left
+  class:overlay
   class:expandedHamburger
   class:expandedBar
   {...el}
@@ -28,19 +36,21 @@ let expandedBar = $state(true);
     class:expander={!expandedHamburger}
     class:close={expandedHamburger}
     aria-label={expandedHamburger ? collapseLabel : expandLabel}
+    aria-expanded={expandedHamburger}
     data-audit-action="toggle-sidebar-sheet"
-    onclick={() => (expandedHamburger = !expandedHamburger)}
+    onclick={() => (open = !expandedHamburger)}
   ></button>
   <div class="content">
     {@render children?.()}
   </div>
   <label class="edge-bar">
     <button
-      onclick={() => (expandedBar = !expandedBar)}
+      onclick={() => (open = !expandedBar)}
       class="expander"
       class:expander={!expandedBar}
       class:close={expandedBar}
-      aria-label={expandedBar ? "Collapse sidebar" : "Expand sidebar"}
+      aria-label={expandedBar ? collapseLabel : expandLabel}
+      aria-expanded={expandedBar}
       data-audit-action="toggle-sidebar-rail"
     ></button>
   </label>
@@ -55,6 +65,18 @@ let expandedBar = $state(true);
    day this mixin got added to a new component. Callers opt in with an actual
    value. (Container does not use this mixin: it wants --gap/auto as its
    defaults, which do not fit the "0 unless asked" contract here.) */
+/* The width at or below which a Sidebar swaps its grab-bar rail for the sheet
+   affordance -- a floating button that opens a panel over the content.
+
+   Page has to agree with Sidebar about this, because Page is what floats the
+   aside out of flow and reserves the strip of padding the sheet button sits
+   in. They used to disagree: Sidebar switched at 512px and Page at 600px,
+   which left a band between 513 and 600 where Page had already lifted the
+   aside out of the layout while the Sidebar inside it was still showing a
+   rail -- a grab bar floating on top of the content, which is the affordance
+   we deliberately avoid everywhere else.
+
+   One definition, used by both, so they cannot drift again. */
 /* Warning: because we define a fallback
   media query, the media query can override the container
   if we stack a bunch of these in a row and aren't thoughtful about the order.
@@ -294,38 +316,392 @@ aside .content:hover::-webkit-scrollbar-thumb:hover {
 }
 
 /* Expander doo-dad */
+/* The sheet affordance: a floating panel you summon with a button and
+   dismiss when you are done with it.
+
+   Used by the compact layout, and by `overlay` at any width. Overlay wants
+   this rather than the rail: a panel that starts open on top of the content
+   is nonsense, and a grab-bar rail floating over the content is a strange
+   thing to ask anyone to grab. A button that opens a sheet is the
+   affordance people already know.
+
+   It keys on .expandedHamburger, which resolves `undefined` to false -- so
+   a sheet starts shut, where the rail starts open. That falls out of the
+   shared `open` state for free. */
 /* Responsive sidebar... */
 @container (min-width: 513px) {
-  /* Aside is a relative container whose width
-  will smoothly animate so our parent knows
-  how to lay us out */
-  aside {
+  /* The rail layout. Everything here is scoped away from `overlay`, which
+     uses the sheet affordance at every width instead. */
+  aside:not(.overlay) {
     transition: width var(--sidebar-transition);
     position: relative;
     height: 100%;
     width: var(--grab-bar-width);
   }
-  aside.expandedBar {
+  aside:not(.overlay).expandedBar {
     width: calc(var(--sidebar-width) + var(--grab-bar-width));
   }
-  aside .content {
+  aside:not(.overlay) .content {
     transition: transform var(--sidebar-transition);
     transform: translateX(-110%);
   }
-  aside.right .content {
+  aside:not(.overlay).right .content {
     transform: translateX(100%);
   }
-  /* Positioning */
-  aside.expandedBar .content {
+  aside:not(.overlay).expandedBar .content {
     transform: translateX(0);
     position: absolute;
     top: 0;
     left: 0;
     width: var(--sidebar-width);
   }
-  aside.expandedBar.right .content {
+  aside:not(.overlay).expandedBar.right .content {
+    left: auto;
+    right: 0;
+  }
+  aside.overlay {
+    /* The sheet and its button are absolutely positioned, so the sidebar has
+       to be their containing block. Without this they resolve against
+       whatever positioned ancestor happens to be up the tree -- inside <Page>
+       that is Page's own aside and it looks fine, but drop a Sidebar into a
+       Card or a Container and the button escapes to the top-left of the page,
+       over unrelated content.
+
+       `overflow` has to be released in the same breath. Every child here is
+       out of flow, so the aside computes to zero height -- harmless while it
+       was not a containing block, but the moment it becomes one the inherited
+       `overflow: hidden` clips the button and the sheet away to nothing.
+       Nothing needs clipping here: the shut sheet is hidden by opacity and
+       pointer-events, not by the box. */
+    /* Sized here rather than on the button, because the panel needs them too
+       -- see the padding it reserves below. */
+    --_sidebar-expander-width: max(
+      var(--sidebar-icon-width, 0.65rem),
+      var(--icon-size, 32px)
+    );
+    --_sidebar-expander-height: max(
+      var(--sidebar-icon-height, 1rem),
+      var(--icon-size, 32px)
+    );
+    position: relative;
+    overflow: visible;
+    background: transparent;
+    width: calc(var(--gap) + max(var(--sidebar-icon-width, 0.65rem), var(--icon-size, 32px)));
+    flex: 0 0 auto;
+    /* Every child is out of flow, so the aside has no content to hold it
+       open and the base `height: 100%` resolves against an auto-height
+       parent -- which is to say, nothing. Stretch to the row instead, so the
+       aside is as tall as whatever it sits beside, and the open sheet's own
+       `height: 100%` has something real to measure against. */
+    height: auto;
+    align-self: stretch;
+  }
+  aside.overlay .edge-bar {
+    display: none;
+  }
+  aside.overlay.right, aside.overlay.left {
+    border-left: none;
+    border-right: none;
+  }
+  aside.overlay > .content {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: var(--sidebar-width);
+    z-index: 2;
+    transform: translateX(-100%);
+    opacity: 0;
+    background: transparent;
+    pointer-events: none;
+    transition: transform var(--sidebar-transition) ease-in-out, opacity var(--sidebar-transition) ease-in-out;
+    padding: var(--padding);
+    /* The close button floats over the panel's inner edge, so the panel has
+       to keep that strip clear or the first nav item sits underneath it.
+
+       Reserved on the inline axis, not the block one: a nav wants the full
+       height, and a blank band across the top of it to clear one button is
+       a poor trade. The cost is that the whole column is a button's width
+       narrower, even well below the button -- override
+       --sidebar-sheet-content-inset to 0 and set your own padding if you
+       would rather have the width back. */
+    padding-inline-end: var(--sidebar-sheet-content-inset, calc(var(--padding) + var(--_sidebar-expander-width)));
+  }
+  aside.overlay.left > .content {
+    border-right: var(--border-width) var(--border-style) var(--border-color);
+  }
+  aside.overlay {
+    /* A right-hand sheet slides out of the right edge, not the left -- and
+       its button lands on the panel's left edge, so the reserved strip
+       mirrors with it. */
+  }
+  aside.overlay.right > .content {
     left: auto;
     right: 0;
+    transform: translateX(100%);
+    border-left: var(--border-width) var(--border-style) var(--border-color);
+    padding-inline-end: var(--padding);
+    padding-inline-start: var(--sidebar-sheet-content-inset, calc(var(--padding) + var(--_sidebar-expander-width)));
+  }
+  aside.overlay.expandedHamburger > .content {
+    transform: translateX(0);
+    height: 100%;
+    opacity: 1;
+    pointer-events: all;
+    box-shadow: var(--sidebar-overlay-box-shadow, var(--overlay-box-shadow, 0 0 var(--space, 8px) rgba(127, 127, 127, 0.4)));
+    --link-bg: var(--sidebar-link-bg, var(--surface-link-bg, inherit));
+    --link-fg: var(--sidebar-link-fg, var(--surface-link-fg, inherit));
+    --_bg-mix-color: var(--sidebar-bg-mix-color, var(--surface-bg-mix-color, var(--bg-mix-color, transparent)));
+    --_bg-mix-amount: var(--sidebar-bg-mix-amount, var(--surface-bg-mix-amount, var(--bg-mix-amount, 0%)));
+    --_fg-mix-color: var(--sidebar-fg-mix-color, var(--surface-fg-mix-color, var(--fg-mix-color, transparent)));
+    --_fg-mix-amount: var(--sidebar-fg-mix-amount, var(--surface-fg-mix-amount, var(--fg-mix-amount, 0%)));
+    --_bg-base: var(--sidebar-bg, var(--surface-bg, var(--bg, unset)));
+    --_fg-base: var(--sidebar-fg, var(--surface-fg, var(--fg, unset)));
+    --_background-color: color-mix(
+      in srgb,
+      var(--_bg-base),
+      var(--_bg-mix-color) var(--_bg-mix-amount)
+    );
+    --_color: color-mix(
+      in srgb,
+      var(--_fg-base),
+      var(--_fg-mix-color) var(--_fg-mix-amount)
+    );
+    --muted-color: var(--muted-color-override, var(--_background-color));
+    --primary-text-fg: var(
+      --primary-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--primary-color)
+          var(--primary-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --secondary-text-fg: var(
+      --secondary-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--secondary-color)
+          var(--secondary-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --info-text-fg: var(
+      --info-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--info-color)
+          var(--info-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --success-text-fg: var(
+      --success-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--success-color)
+          var(--success-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --warning-text-fg: var(
+      --warning-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--warning-color)
+          var(--warning-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --danger-text-fg: var(
+      --danger-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--danger-color)
+          var(--danger-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --muted-text-fg: var(
+      --muted-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--muted-color)
+          var(--muted-text-amount, var(--text-amount, 50%))
+      )
+    );
+    background-color: var(--_background-color);
+    color: var(--_color);
+  }
+  aside.overlay > button {
+    transition: left var(--sidebar-transition);
+    transform: translateX(0);
+    z-index: 3;
+    position: absolute;
+    opacity: 1;
+    pointer-events: all;
+    display: block;
+    top: var(--padding);
+    left: 0;
+    border-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
+    border: var(--circle-button-border, var(--mini-button-border));
+    width: var(--_sidebar-expander-width);
+    height: var(--_sidebar-expander-height);
+    --link-bg: var(--circle-button-link-bg, var(--mini-button-link-bg, var(--button-link-bg, var(--control-link-bg, var(--secondary-link-bg, inherit)))));
+    --link-fg: var(--circle-button-link-fg, var(--mini-button-link-fg, var(--button-link-fg, var(--control-link-fg, var(--secondary-link-fg, inherit)))));
+    --_bg-mix-color: var(--circle-button-bg-mix-color, var(--mini-button-bg-mix-color, var(--button-bg-mix-color, var(--control-bg-mix-color, var(--secondary-bg-mix-color, var(--bg-mix-color, transparent))))));
+    --_bg-mix-amount: var(--circle-button-bg-mix-amount, var(--mini-button-bg-mix-amount, var(--button-bg-mix-amount, var(--control-bg-mix-amount, var(--secondary-bg-mix-amount, var(--bg-mix-amount, 0%))))));
+    --_fg-mix-color: var(--circle-button-fg-mix-color, var(--mini-button-fg-mix-color, var(--button-fg-mix-color, var(--control-fg-mix-color, var(--secondary-fg-mix-color, var(--fg-mix-color, transparent))))));
+    --_fg-mix-amount: var(--circle-button-fg-mix-amount, var(--mini-button-fg-mix-amount, var(--button-fg-mix-amount, var(--control-fg-mix-amount, var(--secondary-fg-mix-amount, var(--fg-mix-amount, 0%))))));
+    --_bg-base: var(--circle-button-bg, var(--mini-button-bg, var(--button-bg, var(--control-bg, var(--secondary-bg, var(--bg, unset))))));
+    --_fg-base: var(--circle-button-fg, var(--mini-button-fg, var(--button-fg, var(--control-fg, var(--secondary-fg, var(--fg, unset))))));
+    --_background-color: color-mix(
+      in srgb,
+      var(--_bg-base),
+      var(--_bg-mix-color) var(--_bg-mix-amount)
+    );
+    --_color: color-mix(
+      in srgb,
+      var(--_fg-base),
+      var(--_fg-mix-color) var(--_fg-mix-amount)
+    );
+    --muted-color: var(--muted-color-override, var(--_background-color));
+    --primary-text-fg: var(
+      --primary-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--primary-color)
+          var(--primary-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --secondary-text-fg: var(
+      --secondary-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--secondary-color)
+          var(--secondary-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --info-text-fg: var(
+      --info-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--info-color)
+          var(--info-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --success-text-fg: var(
+      --success-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--success-color)
+          var(--success-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --warning-text-fg: var(
+      --warning-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--warning-color)
+          var(--warning-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --danger-text-fg: var(
+      --danger-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--danger-color)
+          var(--danger-text-amount, var(--text-amount, 50%))
+      )
+    );
+    --muted-text-fg: var(
+      --muted-text-fg-override,
+      color-mix(
+        in srgb,
+        var(--_color),
+        var(--muted-color)
+          var(--muted-text-amount, var(--text-amount, 50%))
+      )
+    );
+    background-color: var(--_background-color);
+    color: var(--_color);
+    cursor: var(--circle-button-cursor, var(--mini-button-cursor, var(--button-cursor, var(--control-cursor, var(--cursor, pointer)))));
+    transition: filter var(--circle-button-transition, var(--mini-button-transition, var(--button-transition, var(--control-transition, var(--transition, 300ms))))), background-color var(--circle-button-transition, var(--mini-button-transition, var(--button-transition, var(--control-transition, var(--transition, 300ms))))), border-color var(--circle-button-transition, var(--mini-button-transition, var(--button-transition, var(--control-transition, var(--transition, 300ms))))), box-shadow var(--circle-button-transition, var(--mini-button-transition, var(--button-transition, var(--control-transition, var(--transition, 300ms))))), transform var(--circle-button-transition, var(--mini-button-transition, var(--button-transition, var(--control-transition, var(--transition, 300ms)))));
+  }
+  aside.overlay > button:hover {
+    filter: var(--circle-button-hover-filter, var(--mini-button-hover-filter, var(--button-hover-filter, var(--control-hover-filter, var(--hover-filter, brightness(1.05))))));
+    transform: var(--circle-button-hover-transform, var(--mini-button-hover-transform, var(--button-hover-transform, var(--control-hover-transform, var(--hover-transform, none)))));
+    color: var(--_color);
+    background-color: color-mix(in oklch, var(--_background-color) var(--hover-base-color-percentage, 90%), var(--hover-color-mix, white) calc(100% - var(--hover-base-color-percentage, 90%)));
+    box-shadow: var(--circle-button-hover-box-shadow, var(--mini-button-hover-box-shadow, var(--button-hover-box-shadow, var(--control-hover-box-shadow, var(--hover-box-shadow, var(--_box-shadow, none))))));
+  }
+  aside.overlay > button:active {
+    filter: var(--circle-button-active-filter, var(--mini-button-active-filter, var(--button-active-filter, var(--control-active-filter, var(--active-filter, brightness(0.9))))));
+    transform: var(--circle-button-active-transform, var(--mini-button-active-transform, var(--button-active-transform, var(--control-active-transform, var(--active-transform, none)))));
+    background-color: color-mix(in oklch, var(--_background-color) var(--active-base-color-percentage, 90%), var(--active-color-mix, black) calc(100% - var(--active-base-color-percentage, 90%)));
+    box-shadow: var(--circle-button-active-box-shadow, var(--mini-button-active-box-shadow, var(--button-active-box-shadow, var(--control-active-box-shadow, var(--active-box-shadow, var(--_box-shadow, none))))));
+  }
+  aside.overlay > button:disabled {
+    cursor: var(--circle-button-disabled-cursor, var(--mini-button-disabled-cursor, var(--button-disabled-cursor, var(--control-disabled-cursor, var(--disabled-cursor, not-allowed)))));
+    transform: var(--circle-button-disabled-transform, var(--mini-button-disabled-transform, var(--button-disabled-transform, var(--control-disabled-transform, var(--disabled-transform, none)))));
+    filter: var(--circle-button-disabled-filter, var(--mini-button-disabled-filter, var(--button-disabled-filter, var(--control-disabled-filter, var(--disabled-filter, grayscale(0.5))))));
+    background-color: color-mix(in oklch, var(--_background-color) var(--disabled-base-color-percentage, 50%), var(--disabled-color-mix, gray) calc(100% - var(--disabled-base-color-percentage, 50%)));
+    box-shadow: var(--circle-button-disabled-box-shadow, var(--mini-button-disabled-box-shadow, var(--button-disabled-box-shadow, var(--control-disabled-box-shadow, var(--disabled-box-shadow, var(--_box-shadow, none))))));
+  }
+  aside.overlay > button:focus-visible {
+    outline: var(--focus-color, -webkit-focus-ring-color) auto 1px;
+    outline-offset: var(--focus-outline-offset, 2px);
+    box-shadow: var(--focus-ring-box-shadow, 0 0 0 3px var(--focus-shadow-color, rgba(100, 150, 250, 0.5)));
+  }
+  aside.overlay > button::after {
+    color: var(--circle-button-fg, var(--mini-button-fg, currentColor));
+    filter: var(--sidebar-mobile-icon-filter, none);
+  }
+  aside.overlay > button.close {
+    /* Flush inside the panel's inner edge. Adding --padding here pushed the
+       button a padding's worth further in, which left it straddling the
+       edge -- part of it hanging outside the panel -- while the content
+       inset below still reserved the full button width, so the gap between
+       the button and the first nav item came out wider than intended.
+       Either the button pops out of the panel or it sits inside it; this
+       sits inside it, and the inset is then exactly button + one gutter. */
+    left: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
+    border-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+  }
+  aside.overlay {
+    /* Everything above anchors the button to the left, which is right for a
+       left-hand sidebar and nonsense for a right-hand one: the sheet slides
+       out of the right edge, so the button has to hug that edge and then step
+       *inwards* -- leftwards -- by the panel's width when it opens. Anchored
+       from the left it stepped the other way, off the far side of the page
+       entirely, where it could not even be clicked. The flattened corners
+       mirror too, so the button still reads as attached to its own edge. */
+  }
+  aside.overlay.right > button {
+    left: auto;
+    right: 0;
+    border-top-left-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-bottom-left-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+  }
+  aside.overlay.right > button.close {
+    left: auto;
+    right: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
+    border-top-right-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-bottom-right-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
   }
   .edge-bar {
     --link-bg: var(--grab-bar-link-bg, var(--sidebar-link-bg, var(--surface-link-bg, inherit)));
@@ -457,43 +833,101 @@ aside .content:hover::-webkit-scrollbar-thumb:hover {
   aside:has(.edge-bar:hover) .content {
     filter: var(--greyed-out-filter);
   }
-  /* Hide hamburger expander when not in
-  hamburger mode */
-  button {
+  /* Hide the sheet button in rail mode */
+  aside:not(.overlay) > button {
     display: none;
   }
 }
 @container (max-width: 512px) {
-  .edge-bar {
-    display: none;
-  }
-  .sidebar {
+  aside {
+    /* The sheet and its button are absolutely positioned, so the sidebar has
+       to be their containing block. Without this they resolve against
+       whatever positioned ancestor happens to be up the tree -- inside <Page>
+       that is Page's own aside and it looks fine, but drop a Sidebar into a
+       Card or a Container and the button escapes to the top-left of the page,
+       over unrelated content.
+
+       `overflow` has to be released in the same breath. Every child here is
+       out of flow, so the aside computes to zero height -- harmless while it
+       was not a containing block, but the moment it becomes one the inherited
+       `overflow: hidden` clips the button and the sheet away to nothing.
+       Nothing needs clipping here: the shut sheet is hidden by opacity and
+       pointer-events, not by the box. */
+    /* Sized here rather than on the button, because the panel needs them too
+       -- see the padding it reserves below. */
+    --_sidebar-expander-width: max(
+      var(--sidebar-icon-width, 0.65rem),
+      var(--icon-size, 32px)
+    );
+    --_sidebar-expander-height: max(
+      var(--sidebar-icon-height, 1rem),
+      var(--icon-size, 32px)
+    );
+    position: relative;
+    overflow: visible;
     background: transparent;
+    width: calc(var(--gap) + max(var(--sidebar-icon-width, 0.65rem), var(--icon-size, 32px)));
+    flex: 0 0 auto;
+    /* Every child is out of flow, so the aside has no content to hold it
+       open and the base `height: 100%` resolves against an auto-height
+       parent -- which is to say, nothing. Stretch to the row instead, so the
+       aside is as tall as whatever it sits beside, and the open sheet's own
+       `height: 100%` has something real to measure against. */
+    height: auto;
+    align-self: stretch;
+  }
+  aside .edge-bar {
+    display: none;
   }
-  .right,
-  .left {
+  aside.right, aside.left {
     border-left: none;
     border-right: none;
   }
   aside > .content {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: var(--sidebar-width);
+    z-index: 2;
     transform: translateX(-100%);
     opacity: 0;
     background: transparent;
     pointer-events: none;
-    transition: transform var(--sidebar-transition) ease-in-out;
+    transition: transform var(--sidebar-transition) ease-in-out, opacity var(--sidebar-transition) ease-in-out;
     padding: var(--padding);
+    /* The close button floats over the panel's inner edge, so the panel has
+       to keep that strip clear or the first nav item sits underneath it.
+
+       Reserved on the inline axis, not the block one: a nav wants the full
+       height, and a blank band across the top of it to clear one button is
+       a poor trade. The cost is that the whole column is a button's width
+       narrower, even well below the button -- override
+       --sidebar-sheet-content-inset to 0 and set your own padding if you
+       would rather have the width back. */
+    padding-inline-end: var(--sidebar-sheet-content-inset, calc(var(--padding) + var(--_sidebar-expander-width)));
   }
   aside.left > .content {
     border-right: var(--border-width) var(--border-style) var(--border-color);
   }
+  aside {
+    /* A right-hand sheet slides out of the right edge, not the left -- and
+       its button lands on the panel's left edge, so the reserved strip
+       mirrors with it. */
+  }
   aside.right > .content {
+    left: auto;
+    right: 0;
+    transform: translateX(100%);
     border-left: var(--border-width) var(--border-style) var(--border-color);
+    padding-inline-end: var(--padding);
+    padding-inline-start: var(--sidebar-sheet-content-inset, calc(var(--padding) + var(--_sidebar-expander-width)));
   }
   aside.expandedHamburger > .content {
     transform: translateX(0);
     height: 100%;
     opacity: 1;
     pointer-events: all;
+    box-shadow: var(--sidebar-overlay-box-shadow, var(--overlay-box-shadow, 0 0 var(--space, 8px) rgba(127, 127, 127, 0.4)));
     --link-bg: var(--sidebar-link-bg, var(--surface-link-bg, inherit));
     --link-fg: var(--sidebar-link-fg, var(--surface-link-fg, inherit));
     --_bg-mix-color: var(--sidebar-bg-mix-color, var(--surface-bg-mix-color, var(--bg-mix-color, transparent)));
@@ -580,14 +1014,6 @@ aside .content:hover::-webkit-scrollbar-thumb:hover {
     color: var(--_color);
   }
   aside > button {
-    --_sidebar-expander-width: max(
-      var(--sidebar-icon-width, 0.65rem),
-      var(--icon-size, 32px)
-    );
-    --_sidebar-expander-height: max(
-      var(--sidebar-icon-height, 1rem),
-      var(--icon-size, 32px)
-    );
     transition: left var(--sidebar-transition);
     transform: translateX(0);
     z-index: 3;
@@ -595,7 +1021,6 @@ aside .content:hover::-webkit-scrollbar-thumb:hover {
     opacity: 1;
     pointer-events: all;
     display: block;
-    position: absolute;
     top: var(--padding);
     left: 0;
     border-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
@@ -721,28 +1146,42 @@ aside .content:hover::-webkit-scrollbar-thumb:hover {
     filter: var(--sidebar-mobile-icon-filter, none);
   }
   aside > button.close {
-    left: calc(var(--sidebar-width) - var(--_sidebar-expander-width) + var(--padding));
+    /* Flush inside the panel's inner edge. Adding --padding here pushed the
+       button a padding's worth further in, which left it straddling the
+       edge -- part of it hanging outside the panel -- while the content
+       inset below still reserved the full button width, so the gap between
+       the button and the first nav item came out wider than intended.
+       Either the button pops out of the panel or it sits inside it; this
+       sits inside it, and the inset is then exactly button + one gutter. */
+    left: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
     border-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
     border-top-right-radius: 0;
     border-bottom-right-radius: 0;
   }
-  /* aside > button:hover {
-    background: var(--mini-button-hover-bg);
-    color: var(--mini-button-hover-fg);
-  } */
   aside {
-    width: calc(var(--gap) + max(var(--sidebar-icon-width, 0.65rem), var(--icon-size, 32px)));
-    flex: 0 0 auto;
+    /* Everything above anchors the button to the left, which is right for a
+       left-hand sidebar and nonsense for a right-hand one: the sheet slides
+       out of the right edge, so the button has to hug that edge and then step
+       *inwards* -- leftwards -- by the panel's width when it opens. Anchored
+       from the left it stepped the other way, off the far side of the page
+       entirely, where it could not even be clicked. The flattened corners
+       mirror too, so the button still reads as attached to its own edge. */
   }
-  aside .content {
-    position: absolute;
-    --top: calc(
-      var(--padding) +
-        max(var(--sidebar-icon-height, 1rem), var(--icon-size, 32px))
-    );
-    left: 0;
-    width: var(--sidebar-width);
-    z-index: 2;
+  aside.right > button {
+    left: auto;
+    right: 0;
+    border-top-left-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-bottom-left-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+  }
+  aside.right > button.close {
+    left: auto;
+    right: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
+    border-top-right-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-bottom-right-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
   }
 }
 button::after {
@@ -758,14 +1197,34 @@ button::after {
   line-height: 1;
 }
 
-button.expander::after {
-  content: var(--sidebar-expand, "›");
-  background-image: var(--sidebar-expand-image, none);
+/* The rail and the sheet are different affordances and want different
+   glyphs. The rail slides a panel out from the edge it sits on, so a
+   chevron pointing that way says what will happen. The sheet is summoned
+   from nowhere by a free-floating button, where the menu glyph is what
+   people already recognize -- and it closes with an x, not a back-chevron,
+   because there is no edge to slide back into.
+
+   Both still fall through --sidebar-expand / --sidebar-collapse, so setting
+   those restyles every button at once and themes that swap in SVGs keep
+   working unchanged. */
+.edge-bar button.expander::after {
+  content: var(--grab-bar-expand, var(--sidebar-expand, "›"));
+  background-image: var(--grab-bar-expand-image, var(--sidebar-expand-image, none));
+}
+
+.edge-bar button.close::after {
+  content: var(--grab-bar-collapse, var(--sidebar-collapse, "‹"));
+  background-image: var(--grab-bar-collapse-image, var(--sidebar-collapse-image, none));
+}
+
+aside > button.expander::after {
+  content: var(--sidebar-sheet-expand, var(--sidebar-expand, "☰"));
+  background-image: var(--sidebar-sheet-expand-image, var(--sidebar-expand-image, none));
 }
 
-button.close::after {
-  content: var(--sidebar-collapse, "‹");
-  background-image: var(--sidebar-collapse-image, none);
+aside > button.close::after {
+  content: var(--sidebar-sheet-collapse, var(--sidebar-collapse, "✕"));
+  background-image: var(--sidebar-sheet-collapse-image, var(--sidebar-collapse-image, none));
 }
 
 .right button::after {