contain-css-svelte 1.2.3 → 1.4.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, sticky = false, sheetButton = "tab", 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,24 @@ 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:sticky
+  class:button-sheet-toggle={sheetButton === "button"}
   class:expandedHamburger
   class:expandedBar
   {...el}
@@ -28,25 +38,53 @@ 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>
 </aside>
 
 <style>@charset "UTF-8";
+/* Per-level heading (h1-h6) box/typography properties, resolved to PRIVATE,
+   inheriting custom properties (--_h1-color, --_h2-font-size, etc) rather than
+   assigned directly to a matched h1-h6 selector. Nothing in this file matches
+   an actual heading element anymore -- see typography-context.css (vars/), which
+   is the single, global, :where()-scoped rule that actually reads these vars
+   and applies them to real elements. That split is what lets a component
+   nested arbitrarily deep (through <article>, <Tile>, whatever) still get the
+   nearest ancestor's heading styling: these are ordinary inherited custom
+   properties, so DOM proximity decides which component's values apply, not
+   selector specificity or stylesheet order. See AGENTS-INTERNAL.md. */
+/* All six heading levels' context vars in one call -- what every
+   "typography container" component (Container, Card, Tile, TextLayout, ...)
+   includes on itself once, alongside the shared --_heading-* vars below. */
+/* Shared prose-measure group: p, blockquote, dl, ul, ol. li/dt/dd don't get
+   their own vars -- they're never wider than their ul/ol/dl parent's own
+   max-width box, so they're already bounded for free by ordinary block
+   layout, not by anything selector-based reaching them individually. */
+/* p specifically also gets the fuller typography-props-bare treatment
+   (paragraph-prefixed), which -- same as in the original selector-based
+   version -- is declared/consumed AFTER the shared prose vars above, so it
+   wins for whichever properties both groups set. */
+/* The first paragraph in a typography context (p:first-of-type, or a p right
+   after a heading) gets its own, slightly different treatment -- larger lede
+   text, no top margin. Structural matching (:first-of-type, `h1 + p`) still
+   has to happen where the real element is, in the global consumer rule; only
+   the VALUES move to context vars here. */
 /* Logical, not top/bottom/left/right: margin-block/margin-inline already take
    one value (both sides equal) or two (start end), so there is no separate
    "which side" prop to remember and no 4-value shorthand order to get wrong.
@@ -55,6 +93,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.
@@ -63,6 +113,9 @@ let expandedBar = $state(true);
   */
 /* Convenience groupings */
 aside {
+  /* Set only by `sheetButton="button"` (below); cleared here so it never
+     leaks in from an enclosing sidebar. */
+  --_sidebar-sheet-edge-override: initial;
   --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)));
@@ -294,38 +347,491 @@ 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)
+    );
+    /* The sheet button's corners. Its "edge" corners are the pair on the
+       side it attaches to -- the page edge while shut, the panel's inner edge
+       while open -- and default to 0, which is what makes it read as a tab
+       fastened to that edge. `sheetButton="button"` rounds them like the
+       other two, for a sheet that does not sit against an edge. */
+    --_sidebar-sheet-button-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    --_sidebar-sheet-expand-edge-radius: var(
+      --sidebar-sheet-expand-edge-radius,
+      var(
+        --_sidebar-sheet-edge-override,
+        var(--sidebar-sheet-edge-radius, 0)
+      )
+    );
+    --_sidebar-sheet-collapse-edge-radius: var(
+      --sidebar-sheet-collapse-edge-radius,
+      var(
+        --_sidebar-sheet-edge-override,
+        var(--sidebar-sheet-edge-radius, 0)
+      )
+    );
+    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);
+    /* Above a sticky Table head (z-index 2), which a sheet beside a long table
+       otherwise slides under. */
+    z-index: var(--sidebar-overlay-z-index, 3);
+    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: calc(var(--sidebar-overlay-z-index, 3) + 1);
+    position: absolute;
+    opacity: 1;
+    pointer-events: all;
+    display: block;
+    top: var(--padding);
+    left: 0;
+    border-radius: var(--_sidebar-sheet-button-radius);
+    border-top-left-radius: var(--_sidebar-sheet-expand-edge-radius);
+    border-bottom-left-radius: var(--_sidebar-sheet-expand-edge-radius);
+    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(--_sidebar-sheet-button-radius);
+    border-top-right-radius: var(--_sidebar-sheet-collapse-edge-radius);
+    border-bottom-right-radius: var(--_sidebar-sheet-collapse-edge-radius);
+  }
+  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-radius: var(--_sidebar-sheet-button-radius);
+    border-top-right-radius: var(--_sidebar-sheet-expand-edge-radius);
+    border-bottom-right-radius: var(--_sidebar-sheet-expand-edge-radius);
+  }
+  aside.overlay.right > button.close {
+    left: auto;
+    right: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
+    border-radius: var(--_sidebar-sheet-button-radius);
+    border-top-left-radius: var(--_sidebar-sheet-collapse-edge-radius);
+    border-bottom-left-radius: var(--_sidebar-sheet-collapse-edge-radius);
+  }
+  aside.overlay {
+    /* `sticky`: the sheet follows the reader down the page instead of
+       stretching to the row.
+
+       Sticky needs the sheet back *in flow* -- an absolutely positioned box
+       cannot stick -- but the aside is only a button's width wide and the
+       row's full height, and that height is exactly the range the sheet
+       should be free to travel. So the aside becomes a one-cell grid as tall
+       as its row, and the sheet and its button share that cell, each sticky
+       within it.
+
+       Horizontal placement moves from `left`/`right` onto margins, because on
+       a sticky box `left` and `right` stop being offsets and become sticky
+       insets -- they would pin the button against a sideways-scrolling
+       ancestor rather than place it. The margins reproduce the absolute
+       geometry exactly: the aside is `--gap` plus one button wide, and a
+       sheet or button wider than that spills out of its cell on the side
+       that faces the content. */
+  }
+  aside.overlay.sticky {
+    --_sidebar-sheet-top: var(--sidebar-sheet-top, var(--padding));
+    --_sidebar-aside-width: calc(var(--gap) + var(--_sidebar-expander-width));
+    display: grid;
+    grid-template-columns: 100%;
+    align-content: stretch;
+    /* A shut sheet is still in flow now, and would otherwise hold the row
+       open to its own height. The aside's width is set explicitly, so
+       size containment only ever zeroes out the height it would have
+       contributed; the row still stretches it to full height. */
+    contain: size;
+  }
+  aside.overlay.sticky > .content, aside.overlay.sticky > button.expander, aside.overlay.sticky > button.close {
+    grid-area: 1/1;
+    position: sticky;
+    align-self: start;
+    justify-self: start;
+    left: auto;
+    right: auto;
+  }
+  aside.overlay.sticky > .content {
+    top: var(--_sidebar-sheet-top);
+    margin-left: 0;
+    height: auto;
+    /* The reserve is a budget for everything that is not the sheet, rather
+       than just the sticky offset: before the sheet sticks -- page scrolled
+       to the top -- its top edge is its row's, which may sit well below the
+       viewport top, and a sheet sized only from the offset would overflow
+       the viewport by exactly that much. Twice the top gives it an even
+       margin at both ends once it has stuck. */
+    max-height: var(--sidebar-sheet-max-height, calc(100dvh - var(--sidebar-sheet-reserve, calc(2 * var(--_sidebar-sheet-top)))));
+    overflow-y: auto;
+    /* A column, so a child with `min-height: 0` and its own overflow can
+       keep a header or footer in view and scroll only its middle. Children
+       that do not opt in keep their size, and the sheet scrolls as a
+       whole. */
+    display: flex;
+    flex-direction: column;
+  }
+  aside.overlay.sticky.expandedHamburger > .content {
+    height: auto;
+  }
+  aside.overlay.sticky.right > .content {
+    margin-left: calc(var(--_sidebar-aside-width) - var(--sidebar-width));
+  }
+  aside.overlay.sticky > button.expander, aside.overlay.sticky > button.close {
+    top: calc(var(--_sidebar-sheet-top) + var(--padding));
+    margin-top: var(--padding);
+    margin-left: 0;
+    transition: margin-left var(--sidebar-transition);
+  }
+  aside.overlay.sticky > button.close {
+    margin-left: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
+  }
+  aside.overlay.sticky.right > button.expander {
+    margin-left: var(--gap);
+  }
+  aside.overlay.sticky.right > button.close {
+    margin-left: calc(var(--_sidebar-aside-width) - var(--sidebar-width));
   }
   .edge-bar {
     --link-bg: var(--grab-bar-link-bg, var(--sidebar-link-bg, var(--surface-link-bg, inherit)));
@@ -457,43 +963,123 @@ 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)
+    );
+    /* The sheet button's corners. Its "edge" corners are the pair on the
+       side it attaches to -- the page edge while shut, the panel's inner edge
+       while open -- and default to 0, which is what makes it read as a tab
+       fastened to that edge. `sheetButton="button"` rounds them like the
+       other two, for a sheet that does not sit against an edge. */
+    --_sidebar-sheet-button-radius: var(--circle-button-radius, var(--mini-button-radius, var(--button-radius, var(--radius, 50%))));
+    --_sidebar-sheet-expand-edge-radius: var(
+      --sidebar-sheet-expand-edge-radius,
+      var(
+        --_sidebar-sheet-edge-override,
+        var(--sidebar-sheet-edge-radius, 0)
+      )
+    );
+    --_sidebar-sheet-collapse-edge-radius: var(
+      --sidebar-sheet-collapse-edge-radius,
+      var(
+        --_sidebar-sheet-edge-override,
+        var(--sidebar-sheet-edge-radius, 0)
+      )
+    );
+    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);
+    /* Above a sticky Table head (z-index 2), which a sheet beside a long table
+       otherwise slides under. */
+    z-index: var(--sidebar-overlay-z-index, 3);
     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,27 +1166,18 @@ 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;
+    z-index: calc(var(--sidebar-overlay-z-index, 3) + 1);
     position: absolute;
     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%))));
-    border-top-left-radius: 0;
-    border-bottom-left-radius: 0;
+    border-radius: var(--_sidebar-sheet-button-radius);
+    border-top-left-radius: var(--_sidebar-sheet-expand-edge-radius);
+    border-bottom-left-radius: var(--_sidebar-sheet-expand-edge-radius);
     border: var(--circle-button-border, var(--mini-button-border));
     width: var(--_sidebar-expander-width);
     height: var(--_sidebar-expander-height);
@@ -721,30 +1298,125 @@ 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));
-    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);
-  } */
+    /* 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(--_sidebar-sheet-button-radius);
+    border-top-right-radius: var(--_sidebar-sheet-collapse-edge-radius);
+    border-bottom-right-radius: var(--_sidebar-sheet-collapse-edge-radius);
+  }
   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-radius: var(--_sidebar-sheet-button-radius);
+    border-top-right-radius: var(--_sidebar-sheet-expand-edge-radius);
+    border-bottom-right-radius: var(--_sidebar-sheet-expand-edge-radius);
+  }
+  aside.right > button.close {
+    left: auto;
+    right: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
+    border-radius: var(--_sidebar-sheet-button-radius);
+    border-top-left-radius: var(--_sidebar-sheet-collapse-edge-radius);
+    border-bottom-left-radius: var(--_sidebar-sheet-collapse-edge-radius);
+  }
+  aside {
+    /* `sticky`: the sheet follows the reader down the page instead of
+       stretching to the row.
+
+       Sticky needs the sheet back *in flow* -- an absolutely positioned box
+       cannot stick -- but the aside is only a button's width wide and the
+       row's full height, and that height is exactly the range the sheet
+       should be free to travel. So the aside becomes a one-cell grid as tall
+       as its row, and the sheet and its button share that cell, each sticky
+       within it.
+
+       Horizontal placement moves from `left`/`right` onto margins, because on
+       a sticky box `left` and `right` stop being offsets and become sticky
+       insets -- they would pin the button against a sideways-scrolling
+       ancestor rather than place it. The margins reproduce the absolute
+       geometry exactly: the aside is `--gap` plus one button wide, and a
+       sheet or button wider than that spills out of its cell on the side
+       that faces the content. */
+  }
+  aside.sticky {
+    --_sidebar-sheet-top: var(--sidebar-sheet-top, var(--padding));
+    --_sidebar-aside-width: calc(var(--gap) + var(--_sidebar-expander-width));
+    display: grid;
+    grid-template-columns: 100%;
+    align-content: stretch;
+    /* A shut sheet is still in flow now, and would otherwise hold the row
+       open to its own height. The aside's width is set explicitly, so
+       size containment only ever zeroes out the height it would have
+       contributed; the row still stretches it to full height. */
+    contain: size;
+  }
+  aside.sticky > .content, aside.sticky > button.expander, aside.sticky > button.close {
+    grid-area: 1/1;
+    position: sticky;
+    align-self: start;
+    justify-self: start;
+    left: auto;
+    right: auto;
+  }
+  aside.sticky > .content {
+    top: var(--_sidebar-sheet-top);
+    margin-left: 0;
+    height: auto;
+    /* The reserve is a budget for everything that is not the sheet, rather
+       than just the sticky offset: before the sheet sticks -- page scrolled
+       to the top -- its top edge is its row's, which may sit well below the
+       viewport top, and a sheet sized only from the offset would overflow
+       the viewport by exactly that much. Twice the top gives it an even
+       margin at both ends once it has stuck. */
+    max-height: var(--sidebar-sheet-max-height, calc(100dvh - var(--sidebar-sheet-reserve, calc(2 * var(--_sidebar-sheet-top)))));
+    overflow-y: auto;
+    /* A column, so a child with `min-height: 0` and its own overflow can
+       keep a header or footer in view and scroll only its middle. Children
+       that do not opt in keep their size, and the sheet scrolls as a
+       whole. */
+    display: flex;
+    flex-direction: column;
+  }
+  aside.sticky.expandedHamburger > .content {
+    height: auto;
+  }
+  aside.sticky.right > .content {
+    margin-left: calc(var(--_sidebar-aside-width) - var(--sidebar-width));
   }
+  aside.sticky > button.expander, aside.sticky > button.close {
+    top: calc(var(--_sidebar-sheet-top) + var(--padding));
+    margin-top: var(--padding);
+    margin-left: 0;
+    transition: margin-left var(--sidebar-transition);
+  }
+  aside.sticky > button.close {
+    margin-left: calc(var(--sidebar-width) - var(--_sidebar-expander-width));
+  }
+  aside.sticky.right > button.expander {
+    margin-left: var(--gap);
+  }
+  aside.sticky.right > button.close {
+    margin-left: calc(var(--_sidebar-aside-width) - var(--sidebar-width));
+  }
+}
+aside.button-sheet-toggle {
+  --_sidebar-sheet-edge-override: var(--_sidebar-sheet-button-radius);
 }
+
 button::after {
   color: var(--sidebar-icon-fg, var(--fg, currentColor));
   background-position: center;
@@ -758,14 +1430,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 {