@kerfjs/ui 5.0.0-beta.100 → 5.0.0-beta.101

package/dist/styles/foundation.css

@@ -98,12 +98,30 @@
   --_kui-popup-row-icon-gap: 0.5rem;
   --_kui-popup-row-label-padding-block: 0.35rem;
   --_kui-popup-row-label-line-height: 1.25;
+  --_kui-popup-group-title-padding: 0.2rem 0.75rem 0.3rem;
+  --_kui-popup-group-title-font-weight: 750;
+  --_kui-popup-caret-open-rotation: -180deg;
+  /* The theme's brand text color as the root resolves it. A scoped tint
+     clamps its lightness for links and brand text (below); it lives outside
+     the palette block, so a tint inherits the root's brand rather than
+     re-deriving from itself. */
+  --_kui-tint-brand-source: var(--kui-color-brand-on-quiet);
+  --_kui-popup-caret-transition: rotate var(--wa-transition-slow, 0.3s)
+    var(--wa-transition-easing, ease);
+}
+
+/* The palette. A scoped tint ([data-kui-tint], below) re-declares this whole
+   block on its element: an unregistered custom property substitutes its var()
+   references where it is declared, so a derived token (the chrome material, a
+   quiet fill mixed into the surface, a popup's current row) resolved at the
+   root would keep the root's colors inside the tint. Only color tokens live
+   here, so a tint never resets an app's spacing or geometry override. */
+:root,
+[data-kui-tint] {
   --_kui-popup-row-current-background: var(--kui-color-brand-fill-normal);
   /* Current row text sits on the brand fill; the darker on-fill accent clears
      WCAG AA there (brand-on-quiet is 4.26:1 over that fill). */
   --_kui-popup-row-current-color: var(--kui-color-brand-on-fill);
-  --_kui-popup-group-title-padding: 0.2rem 0.75rem 0.3rem;
-  --_kui-popup-group-title-font-weight: 750;
   /* A capped, scrolling popup shows that it scrolls: a soft shadow along an
      edge while more choices lie beyond it. Covers painted in the surface
      color scroll with the content (`local`) and hide each shadow (`scroll`,
@@ -130,9 +148,6 @@
       )
       center bottom / 100% 0.75rem no-repeat scroll,
     var(--kui-color-surface-raised);
-  --_kui-popup-caret-open-rotation: -180deg;
-  --_kui-popup-caret-transition: rotate var(--wa-transition-slow, 0.3s)
-    var(--wa-transition-easing, ease);
   /* macOS Tahoe light semantics used by Hot Sheet 2, with a compatible dark extension. */
   /* Every --kui-color-* token (and the focus-ring color) that reads a --wa-*
      token falls back to the value src/webawesome.css assigns to that token,
@@ -527,10 +542,127 @@
   --kui-safe-area-inline-end: env(safe-area-inset-left, 0px);
 }
 
+/* Scoped tint. A Pane, NavStack, or TabNavigator `tint` ({ color, scheme })
+   marks its root `data-kui-tint="<scheme>"` with the color in
+   `--_kui-tint-color`. The app declares the scheme (there is no automatic
+   color detection), and the scope re-derives the base surface and text
+   tokens from the color; the palette block above then re-derives everything
+   built on them (raised and lowered surfaces, quiet fills, the chrome
+   material). Relative color syntax clamps each token's lightness to a band
+   that holds WCAG AA whatever the color: a light tint's surface stays at or
+   above 90% OKLCH lightness under 24% text, 44% quiet text, and brand text
+   at most 45%, and a dark tint's surface at or below 30% under 97% text, 80%
+   quiet text, and brand text at least 80%. Chroma is capped so
+   text stays near-neutral and a surface stays a tint, not a fill.
+   Without relative color syntax, and under `prefers-contrast: more`, the
+   scope keeps the plain palette in its declared scheme. */
+[data-kui-tint="light"] {
+  color-scheme: light;
+}
+
+[data-kui-tint="dark"] {
+  color-scheme: dark;
+}
+
+/* Inside a tint the chrome material keeps its blur but drops the saturation
+   boost: over the scope's own colored surface, saturating it would paint a
+   visibly brighter band (and a lighter edge) under an overlay header at
+   rest, where the header should read as the same surface. */
+[data-kui-tint] {
+  color: var(--kui-color-text);
+  --kui-chrome-material-filter: blur(20px);
+}
+
+@supports (color: oklch(from red l c h)) {
+  @media not (prefers-contrast: more) {
+    [data-kui-tint="light"] {
+      --wa-color-surface-default: oklch(
+        from var(--_kui-tint-color) clamp(0.9, l, 0.985) min(c, 0.08) h
+      );
+      --wa-color-surface-raised: oklch(
+        from var(--_kui-tint-color) min(1, calc(clamp(0.9, l, 0.985) + 0.03))
+          min(c, 0.05) h
+      );
+      --wa-color-text-normal: oklch(
+        from var(--_kui-tint-color) 0.24 min(c, 0.03) h
+      );
+      --wa-color-text-quiet: oklch(
+        from var(--_kui-tint-color) 0.44 min(c, 0.04) h
+      );
+      --wa-color-neutral-on-quiet: oklch(
+        from var(--_kui-tint-color) 0.42 min(c, 0.04) h
+      );
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-brand-source) min(l, 0.45) c h
+      );
+    }
+
+    [data-kui-tint="dark"] {
+      --wa-color-surface-default: oklch(
+        from var(--_kui-tint-color) clamp(0.16, l, 0.3) min(c, 0.1) h
+      );
+      --wa-color-surface-raised: oklch(
+        from var(--_kui-tint-color) calc(clamp(0.16, l, 0.3) + 0.06)
+          min(c, 0.08) h
+      );
+      --wa-color-text-normal: oklch(
+        from var(--_kui-tint-color) 0.97 min(c, 0.02) h
+      );
+      --wa-color-text-quiet: oklch(
+        from var(--_kui-tint-color) 0.8 min(c, 0.04) h
+      );
+      --wa-color-neutral-on-quiet: oklch(
+        from var(--_kui-tint-color) 0.82 min(c, 0.04) h
+      );
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-brand-source) max(l, 0.8) c h
+      );
+    }
+
+    /* An optional accent (`tint.accent`) re-derives the brand ramp in the
+       scope: the loud fill (buttons, the current row, checked controls), its
+       on-loud text, brand text and links, text on brand fills, and the focus
+       ring. Lightness is clamped so each pair keeps WCAG AA for any accent:
+       a light scope's fill stays at or below 50% under white text, a dark
+       scope's between 72% and 85% under near-black text, and brand text at
+       most 45% (light) or at least 80% (dark). */
+    [data-kui-tint="light"][data-kui-tint-accent] {
+      --wa-color-brand-fill-loud: oklch(
+        from var(--_kui-tint-accent) min(l, 0.5) c h
+      );
+      --wa-color-brand-on-loud: #fff;
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-accent) min(l, 0.45) c h
+      );
+      --kui-color-brand-on-fill: oklch(
+        from var(--_kui-tint-accent) min(l, 0.38) c h
+      );
+      --wa-color-focus: oklch(from var(--_kui-tint-accent) min(l, 0.5) c h);
+    }
+
+    [data-kui-tint="dark"][data-kui-tint-accent] {
+      --wa-color-brand-fill-loud: oklch(
+        from var(--_kui-tint-accent) clamp(0.72, l, 0.85) c h
+      );
+      --wa-color-brand-on-loud: #111113;
+      --wa-color-brand-on-quiet: oklch(
+        from var(--_kui-tint-accent) max(l, 0.8) c h
+      );
+      --kui-color-brand-on-fill: oklch(
+        from var(--_kui-tint-accent) max(l, 0.82) c h
+      );
+      --wa-color-focus: oklch(
+        from var(--_kui-tint-accent) clamp(0.72, l, 0.85) c h
+      );
+    }
+  }
+}
+
 @supports not (
   (backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))
 ) {
-  :root {
+  :root,
+  [data-kui-tint] {
     --kui-chrome-material: var(--kui-color-surface);
     --kui-chrome-material-raised: var(--kui-color-surface-raised);
     --kui-chrome-material-filter: none;
@@ -538,7 +670,31 @@
 }
 
 @media (prefers-reduced-transparency: reduce), (prefers-contrast: more) {
-  :root {
+  :root,
+  [data-kui-tint] {
+    --kui-chrome-material: var(--kui-color-surface);
+    --kui-chrome-material-raised: var(--kui-color-surface-raised);
+    --kui-chrome-material-filter: none;
+  }
+}
+
+/* The static-effects switch. There is no reliable CSS signal for a low-power
+   or slow device, so an app that detects one itself sets
+   `data-kui-effects="static"` on the root element; a display that cannot
+   animate smoothly (`update: slow`, e-ink and similar) gets the same result
+   on its own. Either way every backdrop effect turns opaque here, and every
+   scroll-driven animation a component owns stops in that component's CSS
+   (tests/unit/static-effects.test.ts holds each one to it). */
+:root[data-kui-effects="static"],
+:root[data-kui-effects="static"] [data-kui-tint] {
+  --kui-chrome-material: var(--kui-color-surface);
+  --kui-chrome-material-raised: var(--kui-color-surface-raised);
+  --kui-chrome-material-filter: none;
+}
+
+@media (update: slow) {
+  :root,
+  [data-kui-tint] {
     --kui-chrome-material: var(--kui-color-surface);
     --kui-chrome-material-raised: var(--kui-color-surface-raised);
     --kui-chrome-material-filter: none;
@@ -546,7 +702,8 @@
 }
 
 @media (prefers-contrast: more) {
-  :root {
+  :root,
+  [data-kui-tint] {
     --kui-color-pop-fill-quiet: Canvas;
     --kui-color-pop-fill-normal: Canvas;
     --kui-color-pop-fill-loud: Highlight;

package/dist/styles/nav-stack.css

@@ -6,7 +6,7 @@
   height: 100%;
   overflow: hidden;
   flex-direction: column;
-  background: var(--kui-color-surface);
+  background: var(--_kui-nav-stack-background, var(--kui-color-surface));
   /* Safe areas: the stack's surfaces paint through unsafe areas; its chrome,
      bottom toolbar, and each view compensate for the edges the stack still
      touches (see pane.css for the `--kui-edge-inset-*` edge context). */
@@ -60,6 +60,25 @@
   opacity: 0;
 }
 
+/* `background`: the stack's color paints the stack, its docked chrome and
+   bottom toolbar, and every view (a view's own `pane.background` paints over
+   it). Overlay chrome keeps the chrome material. A nested stack never
+   inherits the color. Forced colors paint the system surface. */
+.kui-nav-stack:not([data-background]) {
+  --_kui-nav-stack-background: initial;
+}
+
+@media (forced-colors: active) {
+  .kui-nav-stack[data-background],
+  .kui-nav-stack[data-background]
+    > :is(.kui-nav-stack__chrome, .kui-nav-stack__bottom),
+  .kui-nav-stack[data-background]
+    > .kui-nav-stack__viewport
+    > .kui-nav-stack__view {
+    background: Canvas;
+  }
+}
+
 /* The chrome hosts the stack's real top Toolbar. It hands that toolbar the
    edges the stack still touches through the edge context (never the bottom,
    which the viewport owns); the toolbar pads for the sides it claims with
@@ -68,7 +87,7 @@
   --kui-edge-inset-block-start: var(--_kui-nav-stack-safe-block-start);
   --kui-edge-inset-inline-start: var(--_kui-nav-stack-safe-inline-start);
   --kui-edge-inset-inline-end: var(--_kui-nav-stack-safe-inline-end);
-  background: var(--kui-color-surface);
+  background: var(--_kui-nav-stack-background, var(--kui-color-surface));
 }
 
 .kui-nav-stack__viewport {
@@ -97,7 +116,7 @@
 .kui-nav-stack__view {
   position: absolute;
   overflow: auto;
-  background: var(--kui-color-surface);
+  background: var(--_kui-nav-stack-background, var(--kui-color-surface));
   transition: transform var(--kui-nav-stack-transition-duration, 200ms) ease;
   inset: 0;
 }
@@ -179,7 +198,7 @@
   --kui-edge-inset-inline-end: var(--_kui-nav-stack-safe-inline-end);
   border-block-start: 1px solid
     var(--_kui-nav-stack-bottom-divider, transparent);
-  background: var(--kui-color-surface);
+  background: var(--_kui-nav-stack-background, var(--kui-color-surface));
 }
 
 /* The live chrome is the containing block of its scroll divider; a
@@ -272,6 +291,182 @@
   }
 }
 
+/* `clear` chrome and bottom toolbar: overlay bars (the same measuring,
+   placement, and edge insets as above) that are fully transparent, for
+   chrome over imagery. With `scrollEdge="material"` a pseudo-element
+   carrying the chrome material fades in (opacity only) while the active
+   view's content lies beneath the bar, as `wireScrollDividers` reports, and
+   out at rest. Clear bars draw no scroll divider. */
+.kui-nav-stack[data-chrome-material="clear"] > .kui-nav-stack__chrome {
+  -webkit-backdrop-filter: none;
+  backdrop-filter: none;
+  background: transparent;
+}
+
+:where(.kui-nav-stack[data-chrome-material="clear"][data-scroll-edge])
+  > .kui-nav-stack__chrome:not(.kui-nav-stack__chrome-copy) {
+  position: relative;
+  isolation: isolate;
+}
+
+/* The scroll edge fades in as content scrolls beneath the bar: the wiring
+   publishes `--kui-scroll-edge-progress` (0 at rest, 1 once content lies
+   `scrollEdgeDistance` beyond the bar) and only the layer's opacity follows
+   it; the filter never animates. Unwired, it stays clear. */
+.kui-nav-stack[data-chrome-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__chrome::before {
+  position: absolute;
+  z-index: -1;
+  content: "";
+  inset: 0;
+  opacity: var(--kui-scroll-edge-progress, 0);
+  pointer-events: none;
+}
+
+.kui-nav-stack[data-chrome-material="clear"][data-scroll-edge="material"]
+  > .kui-nav-stack__chrome::before {
+  -webkit-backdrop-filter: var(--kui-chrome-material-filter);
+  backdrop-filter: var(--kui-chrome-material-filter);
+  background: var(--kui-chrome-material);
+}
+
+.kui-nav-stack[data-chrome-material="clear"][data-scroll-edge="surface"]
+  > .kui-nav-stack__chrome::before {
+  background: var(--kui-color-surface);
+}
+
+/* Static effects and slow displays snap the edge on while content lies
+   beneath the bar instead of tracking the scroll. */
+:root[data-kui-effects="static"]
+  .kui-nav-stack[data-chrome-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__chrome::before {
+  opacity: 0;
+}
+
+:root[data-kui-effects="static"]
+  .kui-nav-stack[data-chrome-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__chrome[data-scroll-divider*="b"]::before {
+  opacity: 1;
+}
+
+@media (update: slow) {
+  .kui-nav-stack[data-chrome-material="clear"][data-scroll-edge]
+    > .kui-nav-stack__chrome::before {
+    opacity: 0;
+  }
+
+  .kui-nav-stack[data-chrome-material="clear"][data-scroll-edge]
+    > .kui-nav-stack__chrome[data-scroll-divider*="b"]::before {
+    opacity: 1;
+  }
+}
+
+/* Clear chrome turns opaque where transparency would hurt, like the
+   material itself. */
+@media (prefers-reduced-transparency: reduce), (prefers-contrast: more) {
+  .kui-nav-stack[data-chrome-material="clear"] > .kui-nav-stack__chrome {
+    background: var(--kui-chrome-material);
+  }
+}
+
+@media (forced-colors: active) {
+  .kui-nav-stack[data-chrome-material="clear"] > .kui-nav-stack__chrome {
+    background: Canvas;
+    border-block-end: 1px solid CanvasText;
+  }
+
+  .kui-nav-stack[data-chrome-material="clear"][data-scroll-edge]
+    > .kui-nav-stack__chrome::before {
+    content: none;
+  }
+}
+
+.kui-nav-stack[data-bottom-toolbar-material="clear"] > .kui-nav-stack__bottom {
+  -webkit-backdrop-filter: none;
+  backdrop-filter: none;
+  background: transparent;
+}
+
+:where(.kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge])
+  > .kui-nav-stack__bottom:not(.kui-nav-stack__chrome-copy) {
+  position: relative;
+  isolation: isolate;
+}
+
+/* The scroll edge fades in as content scrolls beneath the bar: the wiring
+   publishes `--kui-scroll-edge-progress` (0 at rest, 1 once content lies
+   `scrollEdgeDistance` beyond the bar) and only the layer's opacity follows
+   it; the filter never animates. Unwired, it stays clear. */
+.kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__bottom::before {
+  position: absolute;
+  z-index: -1;
+  content: "";
+  inset: 0;
+  opacity: var(--kui-scroll-edge-progress, 0);
+  pointer-events: none;
+}
+
+.kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge="material"]
+  > .kui-nav-stack__bottom::before {
+  -webkit-backdrop-filter: var(--kui-chrome-material-filter);
+  backdrop-filter: var(--kui-chrome-material-filter);
+  background: var(--kui-chrome-material);
+}
+
+.kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge="surface"]
+  > .kui-nav-stack__bottom::before {
+  background: var(--kui-color-surface);
+}
+
+/* Static effects and slow displays snap the edge on while content lies
+   beneath the bar instead of tracking the scroll. */
+:root[data-kui-effects="static"]
+  .kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__bottom::before {
+  opacity: 0;
+}
+
+:root[data-kui-effects="static"]
+  .kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge]
+  > .kui-nav-stack__bottom[data-scroll-divider*="t"]::before {
+  opacity: 1;
+}
+
+@media (update: slow) {
+  .kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge]
+    > .kui-nav-stack__bottom::before {
+    opacity: 0;
+  }
+
+  .kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge]
+    > .kui-nav-stack__bottom[data-scroll-divider*="t"]::before {
+    opacity: 1;
+  }
+}
+
+/* Clear chrome turns opaque where transparency would hurt, like the
+   material itself. */
+@media (prefers-reduced-transparency: reduce), (prefers-contrast: more) {
+  .kui-nav-stack[data-bottom-toolbar-material="clear"]
+    > .kui-nav-stack__bottom {
+    background: var(--kui-chrome-material);
+  }
+}
+
+@media (forced-colors: active) {
+  .kui-nav-stack[data-bottom-toolbar-material="clear"]
+    > .kui-nav-stack__bottom {
+    background: Canvas;
+    border-block-start-color: CanvasText;
+  }
+
+  .kui-nav-stack[data-bottom-toolbar-material="clear"][data-scroll-edge]
+    > .kui-nav-stack__bottom::before {
+    content: none;
+  }
+}
+
 /* Chrome dividers: with `chromeDividers="scroll"` (the default, no
    attribute) the top chrome draws a line along its bottom edge while the
    active view's content is scrolled beneath it, and the bottom toolbar
@@ -290,7 +485,10 @@
       > [data-component="pane"][data-appearance="sunken"]
   )
   > .kui-nav-stack__chrome::after,
-.kui-nav-stack[data-separator="auto"]:not([data-chrome-dividers])
+.kui-nav-stack[data-separator="auto"]:not(
+    [data-chrome-dividers],
+    [data-chrome-material="clear"]
+  )
   > .kui-nav-stack__chrome[data-scroll-divider*="b"]::after,
 .kui-nav-stack[data-separator="auto"][data-chrome-dividers="always"]
   > .kui-nav-stack__chrome::after {
@@ -309,7 +507,10 @@
       > [data-component="pane"][data-appearance="sunken"]
   )
   > .kui-nav-stack__bottom,
-.kui-nav-stack[data-separator="auto"]:not([data-chrome-dividers])
+.kui-nav-stack[data-separator="auto"]:not(
+    [data-chrome-dividers],
+    [data-bottom-toolbar-material="clear"]
+  )
   > .kui-nav-stack__bottom[data-scroll-divider*="t"],
 .kui-nav-stack[data-separator="auto"][data-chrome-dividers="always"]
   > .kui-nav-stack__bottom {

package/dist/styles/overlay-sheet.css

@@ -0,0 +1,211 @@
+/* Bottom-sheet presentation for the core `kerfjs/overlay` surfaces: `overlay()`
+   and the `confirm` / `prompt` / `form` / `choice` promise dialogs opened with
+   `presentation: 'bottom-sheet'`. The core ships no CSS; it marks the overlay
+   `data-presentation="bottom-sheet"` and publishes the virtual keyboard's
+   overlap as `--kerf-keyboard-inset`. This opt-in stylesheet gives those
+   sheets the geometry of a `DialogSurface` bottom sheet: resting on the
+   bottom edge with square bottom corners and the dialog radius on top,
+   capped below the top safe area, padded at its block end by the larger of
+   the safe area and the keyboard so its content stays above both, and
+   sliding up as it opens. It styles the plain path (the wrapper is the
+   backdrop and its content the sheet) and the `native: true` path (the
+   `<dialog>` is the sheet). */
+div.kerf-overlay[data-presentation="bottom-sheet"] {
+  position: fixed;
+  z-index: var(--kui-overlay-sheet-z-index, 1000);
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  background: var(
+    --wa-color-overlay-modal,
+    light-dark(rgb(29 29 31 / 0.34), rgb(0 0 0 / 0.6))
+  );
+  inset: 0;
+}
+
+dialog.kerf-overlay[data-presentation="bottom-sheet"]::backdrop {
+  background: var(
+    --wa-color-overlay-modal,
+    light-dark(rgb(29 29 31 / 0.34), rgb(0 0 0 / 0.6))
+  );
+}
+
+div.kerf-overlay[data-presentation="bottom-sheet"] > *,
+dialog.kerf-overlay[data-presentation="bottom-sheet"] {
+  --_kui-overlay-sheet-clearance: max(
+    var(--kui-safe-area-block-end, env(safe-area-inset-bottom, 0px)),
+    var(--kerf-keyboard-inset, 0px)
+  );
+  --_kui-overlay-sheet-cap: calc(
+    100dvh - var(--kui-safe-area-block-start, env(safe-area-inset-top, 0px)) -
+      1rem
+  );
+  --_kui-overlay-sheet-padding-end: calc(
+    var(--kui-space-xs) + var(--_kui-overlay-sheet-clearance)
+  );
+  box-sizing: border-box;
+  width: min(100%, 35rem);
+  max-width: 100%;
+  max-height: var(--_kui-overlay-sheet-cap);
+  margin: 0;
+  /* The 8px surface inset of a DialogSurface body: content items and lists
+     inside own their own inset from there. */
+  padding: var(--kui-space-xs) var(--kui-space-xs)
+    var(--_kui-overlay-sheet-padding-end);
+  overflow: auto;
+  border: 0;
+  /* Concentric with a pill control group at the 8px surface inset, like a
+     DialogSurface. */
+  border-radius: calc(
+      var(--kui-layout-pill-radius, calc(1px + 1.3125rem)) +
+        var(--kui-wa-surface-inset, 0.5rem)
+    )
+    calc(
+      var(--kui-layout-pill-radius, calc(1px + 1.3125rem)) +
+        var(--kui-wa-surface-inset, 0.5rem)
+    )
+    0 0;
+  color: var(--kui-color-text);
+  background: var(--kui-color-surface-raised);
+  box-shadow: var(--kui-shadow-l);
+  overscroll-behavior: contain;
+}
+
+/* The native <dialog> keeps its top-layer placement; only the UA centering
+   gives way to the bottom edge. */
+dialog.kerf-overlay[data-presentation="bottom-sheet"] {
+  margin: auto auto 0;
+}
+
+/* A resizable sheet (the `kui-overlay-sheet-resizable` class, wired by
+   `wireOverlaySheets` from `@kerfjs/ui/wire-overlay-sheets`) carries the
+   grabber of a resizable DialogSurface sheet at its top edge. It opens at its
+   content height; a drag or the keyboard publishes the visible height on the
+   wrapper, between the minimum and the cap. */
+div.kerf-overlay.kui-overlay-sheet-resizable[data-presentation="bottom-sheet"]
+  > *,
+dialog.kerf-overlay.kui-overlay-sheet-resizable[data-presentation="bottom-sheet"] {
+  height: calc(
+    var(--_kui-overlay-sheet-height) + var(--_kui-overlay-sheet-padding-end)
+  );
+  min-height: min(
+    calc(
+      var(--kui-overlay-sheet-min-height, 10rem) +
+        var(--_kui-overlay-sheet-padding-end)
+    ),
+    var(--_kui-overlay-sheet-cap)
+  );
+  padding-block-start: 0;
+}
+
+/* Sticky, so it stays at the top edge while the sheet's content scrolls, and
+   overlapping the content's first 8px, so the content starts 12px down as in
+   a resizable DialogSurface sheet. */
+.kui-overlay-sheet-handle {
+  position: sticky;
+  z-index: 2;
+  inset-block-start: 0;
+  display: block;
+  width: 6rem;
+  height: 1.25rem;
+  margin: 0 auto calc(0.75rem - 1.25rem);
+  border-radius: var(--kui-radius-s);
+  cursor: ns-resize;
+  touch-action: none;
+}
+
+.kui-overlay-sheet-handle::before {
+  position: absolute;
+  inset-block-start: 0.375rem;
+  inset-inline: 0;
+  width: 2.25rem;
+  height: 0.3125rem;
+  margin-inline: auto;
+  border-radius: 0.15625rem;
+  background: var(--kui-color-neutral-border-loud);
+  content: "";
+}
+
+.kui-overlay-sheet-handle:focus-visible {
+  outline: var(--kui-focus-ring);
+  outline-offset: -3px;
+}
+
+@keyframes kui-overlay-sheet-slide {
+  from {
+    translate: 0 100%;
+  }
+  to {
+    translate: 0 0;
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  :root:not([data-kui-effects="static"])
+    div.kerf-overlay[data-presentation="bottom-sheet"]
+    > *,
+  :root:not([data-kui-effects="static"])
+    dialog.kerf-overlay[data-presentation="bottom-sheet"] {
+    animation: kui-overlay-sheet-slide var(--wa-transition-slow, 300ms)
+      cubic-bezier(0.32, 0.72, 0, 1);
+  }
+}
+
+/* Exit motion: pass `exitClass: 'kui-overlay-sheet-exit'` (with an
+   `exitDuration` cap such as 400) to the overlay or promise dialog, and the
+   sheet slides back down while the backdrop fades. The core removes the node
+   once the animations finish, and skips the exit under reduced motion; the
+   static-effects switch leaves nothing running, so it is removed at once. A
+   closed native <dialog> is `display: none`, so the class keeps it painted
+   at the bottom edge for the exit. */
+@keyframes kui-overlay-sheet-slide-out {
+  from {
+    translate: 0 0;
+  }
+  to {
+    translate: 0 100%;
+  }
+}
+
+@keyframes kui-overlay-sheet-backdrop-out {
+  to {
+    background-color: transparent;
+  }
+}
+
+dialog.kerf-overlay[data-presentation="bottom-sheet"].kui-overlay-sheet-exit {
+  display: block;
+  position: fixed;
+  z-index: var(--kui-overlay-sheet-z-index, 1000);
+  inset: auto 0 0;
+  margin-inline: auto;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  :root:not([data-kui-effects="static"])
+    div.kerf-overlay[data-presentation="bottom-sheet"].kui-overlay-sheet-exit {
+    animation: kui-overlay-sheet-backdrop-out var(--wa-transition-slow, 300ms)
+      ease both;
+  }
+
+  :root:not([data-kui-effects="static"])
+    div.kerf-overlay[data-presentation="bottom-sheet"].kui-overlay-sheet-exit
+    > *,
+  :root:not([data-kui-effects="static"])
+    dialog.kerf-overlay[data-presentation="bottom-sheet"].kui-overlay-sheet-exit {
+    animation: kui-overlay-sheet-slide-out var(--wa-transition-slow, 300ms)
+      cubic-bezier(0.32, 0.72, 0, 1) both;
+  }
+}
+
+@media (forced-colors: active) {
+  div.kerf-overlay[data-presentation="bottom-sheet"] > *,
+  dialog.kerf-overlay[data-presentation="bottom-sheet"] {
+    border-block-start: 1px solid CanvasText;
+    background: Canvas;
+  }
+
+  .kui-overlay-sheet-handle::before {
+    background: CanvasText;
+  }
+}