@gjsify/adwaita-web 0.54.0 → 0.56.0

package/scss/_level_bar.scss

@@ -0,0 +1,190 @@
+// _level_bar.scss — <gtk-level-bar>: the trough, the block, and the four colours the
+// offset classes select.
+//
+// THE GEOMETRY IS libadwaita's, VERBATIM, because this widget has no other styling
+// anywhere: refs/libadwaita/src/stylesheet/widgets/_level-bar.scss is the only
+// stylesheet that touches a `levelbar` node, and it is entirely radii, sizes and
+// block colours.
+//
+// WHAT C SUPPLIES INSTEAD. `levelbar > trough > block` is GTK's node tree
+// (gtklevelbar.c:99-116) — the element writes `.adw-level-bar-trough` and
+// `.adw-level-bar-block` with `.filled` / `.empty` plus the offset's class, because the
+// offsets are a RUNTIME list (`gtk_level_bar_add_offset_value`, gtklevelbar.c:1395-1411)
+// and no stylesheet can enumerate what an application adds. The four colours below are
+// therefore written for the classes GTK itself installs: `low`, `high`, `full`
+// (:1058-1060), and an application's own offset reaches them the same way.
+//
+// CONTINUOUS IS TWO NODES, NOT ONE. GTK allocates the empty level full size and paints
+// the filled one over it (gtklevelbar.c:344-362, :424-461), and the filled node is NOT
+// allocated at all when the value is 0 (:429-430) — which is why this partial positions
+// both absolutely inside the trough instead of flowing them, and why `overflow: hidden`
+// stands in for GTK's rounded clip.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_level-bar.scss:1-93
+// Reference: refs/gtk/gtk/gtklevelbar.c:99-116,285-303,344-362,424-461,467-524
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+// $_levelbar_size (level-bar.scss:1)
+$levelbar-size: 8px;
+// $_levelbar_border_radius (level-bar.scss:2)
+$levelbar-radius: 99px;
+
+gtk-level-bar {
+  display: flex;
+
+  // `&:disabled { filter: Opacity(var(--disabled-opacity)) }` (:5-7).
+  &[disabled] {
+    opacity: var(--disabled-opacity);
+  }
+
+  .adw-level-bar-trough {
+    // `> trough { padding: 0 }` (:67-68) — the trough is the whole box, not a padded
+    // container around a smaller trough.
+    padding: 0;
+    position: relative;
+    display: flex;
+    // The rounded clip `gtk_snapshot_push_rounded_clip` puts on a progress node
+    // (gtkprogressbar.c:462-465), and the reason a value past `max-value` is cut off
+    // here rather than drawn beyond the end.
+    overflow: hidden;
+    width: 100%;
+  }
+
+  .adw-level-bar-block {
+    position: absolute;
+    border-radius: $levelbar-radius;
+  }
+
+  // The unfilled level, which is what `block.empty` paints ($trough_color,
+  // level-bar.scss:85-92) — the same 15%-of-currentColor mix the scale trough uses
+  // (_scale.scss:1-10) and the 30% one under high contrast.
+  .adw-level-bar-block.empty {
+    inset: 0;
+    background-color: color-mix(in srgb, currentColor 15%, transparent);
+
+    @media (prefers-contrast: more) {
+      background-color: color-mix(in srgb, currentColor 30%, transparent);
+      box-shadow: inset 0 0 0 1px var(--border-color);
+    }
+  }
+
+  // The block colours (`> trough > block`, :71-93). `&:not(.empty)` is upstream's own
+  // selector, kept as written: it is what lets an offset an application invents paint in
+  // the accent without a rule of its own.
+  .adw-level-bar-block {
+    &.low {
+      background-color: var(--warning-bg-color);
+    }
+
+    &:not(.empty) {
+      background-color: var(--accent-bg-color);
+    }
+
+    &.full {
+      background-color: var(--success-bg-color);
+    }
+
+    &.high {
+      background-color: var(--accent-bg-color);
+    }
+  }
+
+  // `&.horizontal` (:9-35): 8px tall, one filled level in proportion to the interval.
+  &.horizontal {
+    .adw-level-bar-trough {
+      height: $levelbar-size;
+    }
+
+    .adw-level-bar-block {
+      min-height: $levelbar-size;
+    }
+
+    .adw-level-bar-block.filled {
+      inset-block: 0;
+      inset-inline-start: 0;
+      // `(cur_value - min_value) / (max_value - min_value)` (gtklevelbar.c:434-435).
+      width: calc(var(--level-fraction, 0) * 100%);
+    }
+
+    // `if (inverted) block_area.x += width - block_area.width` (:447-448).
+    &[inverted] .adw-level-bar-block.filled {
+      inset-inline-start: auto;
+      inset-inline-end: 0;
+    }
+  }
+
+  // `&.vertical` (:38-64): the same bar across the other axis.
+  &.vertical {
+    .adw-level-bar-trough {
+      height: 100%;
+    }
+
+    .adw-level-bar-block {
+      min-width: $levelbar-size;
+    }
+
+    .adw-level-bar-block.filled {
+      inset-inline: 0;
+      inset-block-start: 0;
+      height: calc(var(--level-fraction, 0) * 100%);
+    }
+
+    // `if (inverted) block_area.y += height - block_area.height` (:455-456).
+    &[inverted] .adw-level-bar-block.filled {
+      inset-block-start: auto;
+      inset-block-end: 0;
+    }
+  }
+
+  // DISCRETE IS FLOW, NOT ABSOLUTE. GTK lays the blocks out in one run and divides the
+  // trough between them (gtklevelbar.c:467-524); libadwaita puts a 2px gap between them
+  // and a 26px minimum (:20-35 horizontal, :50-64 vertical), with the outer corners
+  // rounded and the inner ones square.
+  &.discrete {
+    .adw-level-bar-block {
+      position: relative;
+      inset: auto;
+      flex: 1 1 0;
+      border-radius: 0;
+    }
+
+    &.horizontal {
+      .adw-level-bar-trough {
+        gap: 2px;
+      }
+
+      .adw-level-bar-block {
+        min-width: 26px;
+
+        &:first-child {
+          border-radius: $levelbar-radius 0 0 $levelbar-radius;
+        }
+
+        &:last-child {
+          border-radius: 0 $levelbar-radius $levelbar-radius 0;
+        }
+      }
+    }
+
+    &.vertical {
+      .adw-level-bar-trough {
+        flex-direction: column;
+        gap: 2px;
+      }
+
+      .adw-level-bar-block {
+        min-height: 26px;
+
+        &:first-child {
+          border-radius: $levelbar-radius $levelbar-radius 0 0;
+        }
+
+        &:last-child {
+          border-radius: 0 0 $levelbar-radius $levelbar-radius;
+        }
+      }
+    }
+  }
+}

package/scss/_link.scss

@@ -0,0 +1,82 @@
+// _link.scss — `link` and `button.link`, libadwaita's link treatment.
+//
+// UNSCOPED, because upstream's rule is on the node and the class together
+// (`_links.scss:1-2`) and both spellings have a reader: a `Gtk.Label` that is a link is
+// the `link` node, and a `Gtk.LinkButton` is `button.link`. `<gtk-link-button>` renders an
+// inner `<button class="adw-button link">`, so the class is what the selector needs.
+//
+// THE TWO COLOURS ARE THE PALETTE'S, not new tokens: `$link_color: var(--accent-color)`
+// and `$link_visited_color: color-mix(in srgb, var(--accent-color) 80%, var(--view-fg-color))`
+// (`_colors.scss:265-266`) are Sass variables over tokens this package already has, so a
+// consumer overriding `--accent-color` recolours its links with everything else.
+//
+// THE `:visited` CLAUSE IS PORTED AS A CLASS. Upstream styles GTK's `:visited` state
+// (`:7-9`), which is a state FLAG on the widget (`GTK_STATE_FLAG_VISITED`,
+// gtklinkbutton.c:743) rather than anything a selector can name from outside.
+// `gtk_link_button_set_visited()` flips exactly that flag and no CSS class, so
+// `<gtk-link-button>` writes `.visited` on the inner button and the rule below reads it.
+// `:disabled` needs no such translation: a disabled `<button>` is already the UA's.
+//
+// `font-weight: inherit` and the transparent background in EVERY state (`:38-44`) are
+// upstream's point: a link is a link, not a button that happens to be blue, so the
+// hover/active/checked rules must not paint over it.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_links.scss:1-49
+// Reference: refs/libadwaita/src/stylesheet/_colors.scss:265-266
+// Reference: refs/gtk/gtk/gtklinkbutton.c:380 (the `.link` style class), :646-672 (the
+//   URI tooltip), :742-749 (the VISITED state flag)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web — `:visited` becomes `.visited`, because
+//   a state flag has no CSS spelling a selector can match on.
+
+$link-color: var(--accent-color);
+$link-visited-color: color-mix(in srgb, var(--accent-color) 80%, var(--view-fg-color));
+$osd-link-color: color-mix(in srgb, var(--accent-bg-color) 50%, white);
+
+.link,
+.adw-button.link {
+  color: $link-color;
+  text-decoration: underline;
+  font-weight: inherit;
+
+  &:hover {
+    color: hsl(from $link-color h calc(s * 1.1) calc(l * 1.1));
+  }
+
+  &:active {
+    color: $link-color;
+  }
+
+  &:disabled {
+    color: color-mix(in srgb, currentColor var(--disabled-opacity), transparent);
+  }
+
+  &.visited {
+    color: $link-visited-color;
+  }
+
+  // `.osd &` — a link over content, where the accent is too dark to read.
+  .osd & {
+    color: $osd-link-color;
+
+    &:visited,
+    &.visited {
+      color: color-mix(in srgb, $osd-link-color 60%, currentColor);
+    }
+
+    &:active {
+      color: $osd-link-color;
+    }
+  }
+
+  // Every state transparent: upstream gives `button.link` no background at rest, on
+  // hover, on active or when checked (_links.scss:38-44), so a toggle-button-styled link
+  // cannot paint one.
+  &,
+  &:hover,
+  &:active,
+  &:checked,
+  &.checked {
+    background-color: transparent;
+  }
+}

package/scss/_list_box.scss

@@ -0,0 +1,88 @@
+// _list_box.scss — <gtk-list-box> and its rows, the elements GTK names `list` and `row`.
+//
+// The `list` NODE and the `row` NODE, because upstream writes them as one block and because
+// libadwaita styles them against EACH OTHER: the separator rule is
+// `&.separators:not(.horizontal) > row:not(.separator)` (_lists.scss:29-32), which is a rule
+// about the list's class and the row's own — a port that styled the rows alone could not
+// express it at all.
+//
+// `<gtk-list-box>` IS NOT AN ORIENTABLE, which is worth the header repeating: `GtkListBase` is
+// (gtklistbase.c:2070) and `<gtk-list-view>` therefore takes an `orientation`, while
+// `GtkListBox` has no such property and its rows always run down. So the
+// `&.horizontal` arm of the upstream separator rule has no counterpart here, and the partial
+// draws only the vertical half.
+//
+// The colour tokens are libadwaita's own, spelled with this package's variables:
+// `$view_hover_color` is `currentColor 4%`, `$view_active_color` `currentColor 8%` and
+// `$view_selected_color` `var(--accent-bg-color) 25%` (_colors.scss:263-276).
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss:5-38 (list), :47-95 (row)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+gtk-list-box {
+  display: block;
+  box-sizing: border-box;
+  color: var(--view-fg-color);
+  background-color: var(--view-bg-color);
+  background-clip: padding-box;
+
+  // `listview, list { border-color: $border_color }` (_lists.scss:10) — the upstream rule
+  // names a COLOUR and nothing else, because GTK draws a border only where a width or a
+  // style is set alongside it. So a bare list has no frame, and that is what this is: the
+  // frame used to sit here unconditionally, which made every list read as a card where
+  // libadwaita draws one only for `list.boxed-list` (_lists.scss:520) — `Adw.PreferencesGroup`
+  // carries that one, through `%card` (_preferences.scss:83), so nothing needed it here.
+  border-color: var(--border-color);
+
+  &.view:disabled {
+    color: var(--view-fg-color);
+  }
+}
+
+gtk-list-box-row {
+  display: block;
+  box-sizing: border-box;
+  background-clip: padding-box;
+  // `listview > row { padding: 2px }` (_lists.scss:16-19).
+  padding: 2px;
+
+  &.activatable {
+    cursor: pointer;
+  }
+
+  &:hover {
+    background-color: color-mix(in srgb, currentColor 4%, transparent);
+  }
+
+  &:active {
+    background-color: color-mix(in srgb, currentColor 8%, transparent);
+  }
+
+  // `row &:selected { background-color: $view_selected_color }` (_lists.scss:92-94), with the
+  // hover and active shades over it (_lists.scss:83-89).
+  &.selected {
+    background-color: color-mix(in srgb, var(--accent-bg-color) 25%, transparent);
+  }
+
+  &.selected:hover {
+    background-color: color-mix(in srgb, var(--accent-bg-color) 40%, transparent);
+  }
+
+  &.selected:active {
+    background-color: color-mix(in srgb, var(--accent-bg-color) 50%, transparent);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--accent-color);
+    outline-offset: -2px;
+  }
+}
+
+// `.separators` is the class GTK adds for `show-separators` (gtklistbox.c:4127-4134), and the
+// rule goes on every row but the last — upstream `> row:not(.separator)`, and a
+// `<gtk-separator>` row is not one, so the port's `:last-child` is the same exclusion without
+// giving the separator a class GTK would then have to know about.
+gtk-list-box.separators > gtk-list-box-row:not(:last-child) {
+  border-bottom: 1px solid var(--border-color);
+}

package/scss/_list_view.scss

@@ -0,0 +1,96 @@
+// _list_view.scss — <gtk-list-view>, and the ROW rules its two relatives reuse.
+//
+// UNSCOPED on purpose: `gridview > child` and `columnview > listview > row` are the same
+// selectable, activatable surface as `listview > row`, and upstream writes them as one
+// set of colours in `_lists.scss` and `_views.scss`. The shared half is the
+// `adw-list-selectable` MIXIN below, which `_grid_view.scss` and `_column_view.scss`
+// include rather than restate — the hover/active/selected quartet is four colours per
+// state and a drifted copy is four wrong ones. A mixin and not a `%placeholder`: a
+// placeholder extended across a `@use` boundary emits into the module that DECLARED it,
+// which would put the grid's and the column view's selectors inside this file's output.
+//
+// The colour tokens are libadwaita's own, spelled with this package's variables:
+// `$view_hover_color` is `currentColor 4%`, `$view_active_color` `currentColor 8%` and
+// `$view_selected_color` `var(--accent-bg-color) 25%` (_colors.scss:274-276).
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_lists.scss:5-45, 74-95 (listview, row)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_views.scss:47-50 (rubberband)
+// Reference: refs/libadwaita/src/stylesheet/_colors.scss:263-276 (the four tokens)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+// The hover / active / selected quartet every item surface in the three views wears.
+@mixin adw-list-selectable {
+  background-clip: padding-box;
+
+  &:hover {
+    background-color: color-mix(in srgb, currentColor 4%, transparent);
+  }
+
+  &:active {
+    background-color: color-mix(in srgb, currentColor 8%, transparent);
+  }
+
+  &.selected {
+    background-color: color-mix(in srgb, var(--accent-bg-color) 25%, transparent);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--accent-color);
+    outline-offset: -2px;
+  }
+}
+
+// The band is positioned against the row container, which is why every view's row
+// container is a containing block.
+.adw-rubberband {
+  position: absolute;
+  border: 1px solid var(--accent-color);
+  background-color: color-mix(in srgb, var(--accent-color) 20%, transparent);
+  pointer-events: none;
+}
+
+// The node a factory's label lands in, in all three views.
+.adw-list-item-label {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+gtk-list-view {
+  display: block;
+  box-sizing: border-box;
+  color: var(--view-fg-color);
+  background-color: var(--view-bg-color);
+  background-clip: padding-box;
+
+  .adw-list-view-rows {
+    // `position: relative` is the rubber band's containing block, not decoration.
+    position: relative;
+    display: flex;
+    flex-direction: column;
+  }
+
+  &.horizontal .adw-list-view-rows {
+    flex-direction: row;
+  }
+
+  .adw-list-view-row {
+    @include adw-list-selectable;
+
+    // `listview > row { padding: 2px }` (_lists.scss:16-19).
+    padding: 2px;
+    box-sizing: border-box;
+  }
+
+  // `.separators` is the class GTK adds for `show-separators`; upstream draws the rule on
+  // the BOTTOM of every row but the separator itself, and on the LEFT when horizontal.
+  &.separators:not(.horizontal) .adw-list-view-row:not(:last-child) {
+    border-bottom: 1px solid var(--border-color);
+  }
+
+  &.separators.horizontal .adw-list-view-row:not(:last-child) {
+    border-right: 1px solid var(--border-color);
+  }
+}

package/scss/_media_controls.scss

@@ -0,0 +1,139 @@
+// _media_controls.scss — <gtk-media-controls>: a box of six pixels' spacing, two labels in
+// tabular figures, and a range input.
+//
+// libadwaita has NO `_media-controls.scss`. `GtkMediaControls` is styled only through the
+// `.osd` and `.bottom` classes `ui/gtkvideo.ui` puts on it, which is what `_video.scss` has
+// already spent itself on: the `%osd` surface (_common.scss:43-60) and the 12px padding a
+// standalone OSD toolbar takes (_toolbars.scss:96-100). So this partial is the C's layout
+// and nothing else — the six numbers below are all the template says.
+//
+// THE TEMPLATE'S `spacing` 6 IS THE ONLY LAYOUT PROPERTY THAT SURVIVES.
+// `box { spacing: 6 }` in `ui/gtkmediacontrols.ui` becomes the gap between the play button,
+// the time box and the volume button. Nothing else in the template is a spacing: the time
+// box has none of its own, and the labels sit against the scale with no gap at all, which is
+// why `gap` is applied to the OUTER box only.
+//
+// `font-variant-numeric: tabular-nums` IS BOTH LABELS' `font-features "tnum=1"`. That
+// attribute on each label (`ui/gtkmediacontrols.ui`) is the only reason the class exists, and
+// it is load-bearing rather than cosmetic: a position counting 9→10 must not change the
+// width of the string, or the seek scale beside it shifts sideways once a second. The same
+// declaration `_labels.scss` applies to the `.numeric` utility class reaches a
+// `Gtk.Label`; this widget's labels are spans of the element's own tree, so the class is
+// applied here.
+//
+// THE SEEK SCALE IS `<input type="range">` WITH GTK'S ADJUSTMENT SPELLED OUT.
+// `time_adjustment` is `upper` 10, `step-increment` 1, `page-increment` 10
+// (`ui/gtkmediacontrols.ui`), and every real duration arrives by resetting the adjustment's
+// range to the media's own — so `min` 0, `max` the duration in seconds and `step` 1 second.
+// `page-increment` 10 has no HTML equivalent: a range input's Page key moves by ten STEPS,
+// not by ten units, which is a different thing and cannot be made to agree. That is the one
+// adjustment property that does not survive, and it is worth naming rather than leaving to be
+// discovered.
+//
+// THE VOLUME SLIDE IS THE OTHER ADJUSTMENT, AND IT IS A DIFFERENT SHAPE.
+// `volume_adjustment` is `upper` 1, `step-increment` 0.1, `page-increment` 1, `value` 1 —
+// full scale in tenths — so `min` 0, `max` 1, `step` 0.1. It lives in the volume button's
+// popover because `GtkVolumeButton` IS a menu button with an adjustment popover; the
+// popover surface is `_popovers.scss`'s, reused through the `.adw-popover` class rather than
+// restated here.
+//
+// `.insensitive` IS THE TEMPLATE'S `sensitive` 0. `ui/gtkmediacontrols.ui` sets it on the
+// whole box, and `gtk_media_controls_set_sensitive` is what re-enables it — so a controls
+// bar with no stream attached is inert, which is the state the element renders by default.
+// GTK's `:disabled` opacity is `_buttons.scss`'s `$disabled-opacity`, and the same token is
+// used here for the whole bar rather than per button, because in the C the insensitivity is
+// the CONTAINER's.
+//
+// Reference: refs/gtk/gtk/ui/gtkmediacontrols.ui (the node tree and both adjustments)
+// Reference: refs/libadwaita/src/stylesheet/_common.scss:43-60 (`%osd`, applied by
+//   `_video.scss`), widgets/_toolbars.scss:96-100 (the `.osd` toolbar's 12px padding)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_buttons.scss (`:disabled` opacity)
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+gtk-media-controls {
+  display: flex;
+  align-items: center;
+  color: var(--window-fg-color);
+
+  // `box { sensitive: 0; spacing: 6 }` (ui/gtkmediacontrols.ui).
+  gap: 6px;
+
+  // `gtk_media_controls_set_sensitive` — the container's own insensitivity, which is where
+  // the template puts it. Same token `_buttons.scss` uses for a `:disabled` button.
+  &.insensitive,
+  &:disabled {
+    opacity: var(--disabled-opacity);
+  }
+
+  .adw-media-controls-box {
+    display: flex;
+    flex: 1;
+    gap: 6px;
+    align-items: center;
+    min-width: 0;
+  }
+
+  // `play_button` is a `GtkButton` with `has-frame` 0 — a flat button — and so is the
+  // `volume_button` beside it. `.adw-flat` is this package's flat-button class; `_button.scss`
+  // owns the shape, and nothing here restates it.
+  .adw-media-controls-button {
+    flex-shrink: 0;
+  }
+
+  // `time_box` — the middle `GtkBox`, `hexpand` on the scale inside it.
+  .adw-media-controls-time-box {
+    display: flex;
+    flex: 1;
+    align-items: center;
+    min-width: 0;
+  }
+
+  // BOTH labels' `font-features "tnum=1"` (ui/gtkmediacontrols.ui). Tabular figures, so a
+  // position counting 9→10 does not resize its own string and shift the scale sideways.
+  .adw-media-controls-time-label,
+  .adw-media-controls-duration-label {
+    // `font-variant-numeric: tabular-nums` is a UTILITY class on a label in libadwaita
+    // (`_labels.scss`); it is applied here directly because these are spans of this element's
+    // own tree rather than `<gtk-label>`s a consumer styled.
+    font-variant-numeric: tabular-nums;
+    // The two labels must never be squeezed: they are the numbers the seek bar is read
+    // against, and a truncated `-1:02:03` is worse than a narrower scale.
+    flex-shrink: 0;
+    padding: 0 2px;
+  }
+
+  // `seek_scale` — the `GtkScale`, `hexpand` 1 and `restrict-to-fill-level` 0.
+  .adw-media-controls-seek-scale {
+    flex: 1;
+    min-width: 0;
+    accent-color: var(--accent-color);
+  }
+
+  // The volume button is a POSITIONING context for its own popover, which is what makes the
+  // surface sit below the button rather than beside the bar — `GtkVolumeButton` is a
+  // `GtkMenuButton`, so the surface hangs off its anchor.
+  .adw-media-controls-volume-button {
+    position: relative;
+  }
+
+  // `<gtk-popover>` is this package's ONE popover surface and `_popover.scss`'s header says
+  // why: three hand-rolled copies of the plate disagreed with libadwaita and with each
+  // other before it was lifted out. So the volume slide goes in a real one and this partial
+  // states nothing about its shape — only that it hangs from the button and does not take
+  // clicks meant for the slide.
+  .adw-media-controls-volume-popover {
+    top: calc(100% + 6px);
+    left: 50%;
+    // `_popover.scss`'s own `$popover-gap`, restated here rather than imported: the gap is
+    // the DISTANCE from anchor to surface, which is a property of the anchor's positioning
+    // and belongs to the widget that owns the anchor.
+    transform: translateX(-50%);
+  }
+
+  .adw-media-controls-volume-scale {
+    width: 120px;
+    accent-color: var(--accent-color);
+  }
+}

package/scss/_overlay.scss

@@ -0,0 +1,68 @@
+// _overlay.scss — <gtk-overlay>: a main child, and siblings stacked on top of it.
+//
+// libadwaita has NO `_overlay.scss`: `grep` over `src/stylesheet/widgets/` finds no
+// `overlay` node rule, because an overlay draws nothing of its own — GTK's whole CSS
+// node contract for it is the `overlay` name plus the `.left` / `.right` / `.top` /
+// `.bottom` classes an edge-aligned child is given (gtkoverlay.c:66-71). So this partial
+// is LAYOUT, not a look, and the geometry it encodes is `gtk_overlay_get_child_position`
+// (gtkoverlay.c:130-196) rather than a style.
+//
+//   · `.adw-overlay-child` is `display: contents` so the main child is laid out as a
+//     DIRECT child of the host and the overlay takes its size — which is exactly
+//     gtk_overlay_compute_expand and the "sizes are those of its main child" rule
+//     (gtkoverlay.c:56-58, :291-308). A wrapper that generated a box would put a
+//     layout node between the overlay and the child, and the child's own `hexpand`
+//     would have to be re-implemented here.
+//   · `.adw-overlay-layer` is the box an overlay child is placed in. `inset: 0` over
+//     the whole host is the C's `graphene_rect_init (&bounds, 0, 0, width, height)`
+//     (gtkoverlay.c:214-216), and `display: flex` is what lets a child's own
+//     `[halign]` / `[valign]` auto-margin rules place it — `gtk_overlay_get_child_position`
+//     reads nothing but those two properties.
+//   · `align-items: stretch` is `GTK_ALIGN_FILL` on the cross axis, the default for
+//     `GtkWidget:valign`. A child that names a `valign` carries an auto cross margin,
+//     and a flex item with an auto cross margin does NOT stretch (CSS Flexbox § 9.4),
+//     which is precisely the branch the C takes for START, CENTER and END.
+//   · `pointer-events: none`, re-enabled per child: GTK hands an event to the widget
+//     whose allocation contains it, so an overlay child that is smaller than the overlay
+//     must not make the main child unreachable underneath it.
+//
+// The `:not([halign])` guard on the main axis is the whole of `GTK_ALIGN_FILL` there —
+// `flex-grow` WITHOUT it would be cancelled by the auto margin `_widget.scss` gives a
+// child that names an alignment, since free space is handed to flex-grow first and only
+// the remainder reaches an auto margin. Specificity has to beat `_widget.scss`'s
+// `[halign='start']` (0,1,0), which `:not([halign])` lifts this rule to.
+//
+// Reference: refs/gtk/gtk/gtkoverlay.c (get_child_position, the `overlay` CSS node)
+// Reference: refs/gtk/gtk/gtkoverlaylayout.c (gtk_overlay_child_allocate, clip bounds)
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+gtk-overlay {
+  display: block;
+  position: relative;
+}
+
+.adw-overlay-child {
+  // The main child, in the host's own flow — see the header.
+  display: contents;
+}
+
+.adw-overlay-layer {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: stretch;
+  justify-content: flex-start;
+  pointer-events: none;
+
+  > * {
+    // GTK delivers an event to the widget whose ALLOCATION it lands in (gtkoverlay.c:150-193),
+    // so only the overlay child's own box takes input.
+    pointer-events: auto;
+  }
+
+  // GTK_ALIGN_FILL on the main axis: the child grows to the overlay's whole allocation.
+  > *:not([halign]) {
+    flex: 1 1 auto;
+  }
+}