@gjsify/adwaita-web 0.31.0 → 0.33.0

package/scss/_popover.scss

@@ -0,0 +1,186 @@
+// _popover.scss — <adw-popover>, the one popover surface in this package.
+//
+// It replaces three hand-rolled copies (`.adw-menu-button-popover`,
+// `.adw-drop-down-popover`, `.adw-split-button-menu`) that disagreed with
+// libadwaita AND with each other: 12px / 12px / 9px radius against libadwaita's
+// 15px, two correct three-layer shadows and one invented two-layer one. Nothing
+// compared any of them to the vendored stylesheet, so all three shipped.
+//
+// GROUND TRUTH, AND THE SELECTOR THAT WINS THE CASCADE
+//
+// `popover > contents` is `padding: 8px; border-radius: $popover_radius` plus a
+// three-layer shadow (_popovers.scss:13-21), with a `prefers-contrast: more`
+// variant that swaps the innermost layer for a hairline border (:23-27).
+// `$popover_radius` is `$menu_radius + 6` = 15px (_common.scss:10,13) — not
+// `$card_radius` (12px) and not `$button_radius` (9px), the two tokens the
+// copies reached for.
+//
+// The PADDING has a second, more specific rule: `popover.menu > contents`
+// re-declares `padding: 0` and moves the inset onto the item box as
+// `$menu_margin` (6px) at _menus.scss:58-66. Two element selectors plus a class
+// beats one element selector plus a child, so a MENU popover renders a 6px inset
+// and a plain one an 8px inset. The three copies all used 6px — they were right
+// about the inset for the menus they drew, and wrong only about the radius.
+//
+// We reproduce the menu inset with ONE node instead of GTK's contents+box pair:
+// `[menu]` puts the 6px directly on the surface. Same rendered geometry, and
+// there is no separate box element to hang it on in the DOM.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_popovers.scss:7-28
+// Reference: refs/libadwaita/src/stylesheet/widgets/_menus.scss:58-66, :134-156
+// Reference: refs/libadwaita/src/stylesheet/_common.scss:10-13 ($menu_radius, $menu_margin, $popover_radius)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for the @gjsify/adwaita-web light-DOM custom elements.
+
+// Distance between the anchor and the surface. GTK gets this gap from the
+// popover's arrow, which this port does not draw (`has-arrow` is not modelled —
+// GtkPopover's C is not vendored here). 6px is what the menu button and the
+// drop-down already used; the split button's 4px was the odd one out.
+$popover-gap: 6px;
+
+adw-popover {
+  // $popover_radius = $menu_radius + 6 (_common.scss:10,13). Exposed as a token
+  // so consumers re-theme it the same way as the rest (ADR 0010), with the
+  // libadwaita value as the fallback.
+  --popover-radius: 15px;
+
+  position: absolute;
+  z-index: 10;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  min-width: 120px; // popover.menu > contents (_menus.scss:2-4)
+  padding: 8px; // popover > contents (_popovers.scss:14)
+  border-radius: var(--popover-radius);
+  background-color: var(--popover-bg-color, var(--window-bg-color, #fff));
+  color: var(--popover-fg-color, var(--window-fg-color));
+
+  // The exact three layers of _popovers.scss:18-20. The COUNT is load-bearing:
+  // the split button shipped two.
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.05),
+    0 1px 5px 1px rgba(0, 0, 0, 0.09),
+    0 2px 14px 3px rgba(0, 0, 0, 0.05);
+
+  // _popovers.scss:23-27 — the innermost layer becomes a real hairline so the
+  // surface has a visible edge when the shadow alone is not enough. Missing
+  // from all three copies.
+  @media (prefers-contrast: more) {
+    box-shadow:
+      0 0 0 1px var(--separator-color),
+      0 1px 5px 1px rgba(0, 0, 0, 0.09),
+      0 2px 14px 3px rgba(0, 0, 0, 0.05);
+  }
+
+  // `popover.menu > contents { padding: 0 }` + `$menu_margin` on the item box
+  // (_menus.scss:58-66), flattened onto the single surface node.
+  &[menu] {
+    padding: 6px;
+  }
+
+  // --- Placement. Pure CSS, as it always was: nothing measures a rect and
+  // --- nothing flips on overflow, in either the element or the core.
+  &[data-position='bottom'] {
+    top: calc(100% + #{$popover-gap});
+  }
+
+  &[data-position='top'] {
+    bottom: calc(100% + #{$popover-gap});
+  }
+
+  &[data-position='start'] {
+    top: 0;
+    right: calc(100% + #{$popover-gap});
+  }
+
+  &[data-position='end'] {
+    top: 0;
+    left: calc(100% + #{$popover-gap});
+  }
+
+  // `align` picks the edge the surface lines up with, and only applies on the
+  // vertical axis — a start/end popover is already pinned horizontally.
+  &[data-position='bottom'],
+  &[data-position='top'] {
+    &[data-align='start'] {
+      left: 0;
+    }
+
+    &[data-align='end'] {
+      right: 0;
+    }
+  }
+}
+
+// A popover row — libadwaita's `modelbutton` (_menus.scss:134-156).
+.adw-popover-item {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xs);
+  width: 100%;
+  min-height: 32px; // :135
+  min-width: 40px; // :136
+  margin: 0;
+  // `padding: 0 $menu_padding` (:137) — $menu_padding is 12px (_common.scss:12),
+  // and the vertical inset comes from min-height, not from padding. No 12px
+  // spacing token exists in this port, so the value is literal like the radius.
+  padding: 0 12px;
+  border: none;
+  border-radius: 9px; // $menu_radius (:138) — NOT calc(--button-radius - 2px), which two copies invented
+  background-color: transparent; // :139
+  color: inherit;
+  font-family: var(--font-family);
+  font-size: var(--font-size-base);
+  text-align: start;
+  cursor: pointer;
+  transition: background-color 0.1s ease;
+
+  // `&:hover, &:selected { background-color: $selected_color }` (:141-144).
+  // `:selected` is GTK's keyboard-highlight pseudo-class; in the DOM that state
+  // is focus, so `.selected` (the drop-down's chosen row) and `:focus` share it.
+  &:hover,
+  &:focus,
+  &.selected {
+    background-color: var(--button-hover-color);
+  }
+
+  &:active {
+    background-color: var(--button-active-color); // $selected_active_color (:146-148)
+  }
+
+  // :150-156 — a contrast-mode ring on the same three states.
+  @media (prefers-contrast: more) {
+    &:hover,
+    &:focus,
+    &.selected,
+    &:active {
+      box-shadow: inset 0 0 0 1px var(--separator-color);
+    }
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--accent-color);
+    outline-offset: -2px;
+  }
+
+  &[disabled] {
+    // `--disabled-opacity` is libadwaita's own variable (_colors.scss:320,
+    // 50%); this port does not define it yet, so the fallback carries the value.
+    opacity: var(--disabled-opacity, 0.5);
+    pointer-events: none;
+  }
+}
+
+// Optional heading atop a menu. libadwaita's `label.title` is `font-weight: bold`
+// + `padding: 4px ($menu_padding + 20px)` (_menus.scss:180-183) — 32px of
+// horizontal padding to centre the title over icon-indented rows, which
+// libadwaita's own comment calls out as fragile. This port keeps the tighter
+// inset `.adw-menu-button-title` already shipped rather than changing how the
+// existing menus look; only the class name moved here. A DELIBERATE deviation,
+// not a reading of :180-183.
+.adw-popover-title {
+  padding: 4px var(--spacing-s) 6px;
+  font-weight: 700;
+  opacity: var(--dim-opacity);
+}

package/scss/_preferences.scss

@@ -8,6 +8,14 @@
 adw-preferences-group {
   display: block;
 
+  // An author `display` beats the UA `[hidden] { display: none }` regardless of
+  // specificity, so without this a group hidden through the DOM `hidden`
+  // property would keep rendering — the search treats it as invisible
+  // (`is_visible_group`), and the two must agree.
+  &[hidden] {
+    display: none;
+  }
+
   // The header is a flex row: a title/description label column on the left
   // (stretches to fill) and the optional header-suffix on the trailing edge.
   .adw-preferences-group-header {
@@ -15,6 +23,27 @@ adw-preferences-group {
     align-items: center;
     gap: var(--spacing-s);
     padding: var(--spacing-xs) 2px;
+
+    // An author `display` beats the UA `[hidden] { display: none }` no matter
+    // the specificity, so `headerEl.hidden = true` did NOTHING here: an empty
+    // group kept its header box and its padding.
+    &[hidden] {
+      display: none;
+    }
+
+    // libadwaita's own metrics, keyed off `is_single_line`:
+    // `> box.header:not(.single-line) { margin-bottom: 6px }` and
+    // `> box.single-line { min-height: 34px }`
+    // (refs/libadwaita/src/stylesheet/widgets/_preferences.scss:6-13). A
+    // title-only or suffix-only header is one line tall and needs the height
+    // floor instead of the gap below it.
+    &:not(.single-line) {
+      margin-bottom: 6px;
+    }
+
+    &.single-line {
+      min-height: 34px;
+    }
   }
 
   .adw-preferences-group-labels {

package/scss/_preferences_dialog.scss

@@ -150,5 +150,22 @@ adw-preferences-dialog {
     max-width: 600px;
     margin: 0 auto;
     padding: var(--spacing-xl) var(--spacing-m);
+
+    // The dialog keeps the <adw-preferences-page> ELEMENTS rather than hoisting
+    // their children out — the page's title / name / icon-name are what a
+    // search-result subtitle and a view switcher read. The page therefore has
+    // to be layout-transparent so its groups stay flex items of this column;
+    // a custom element's default `display: inline` would collapse it.
+    > adw-preferences-page {
+      display: contents;
+
+      // `display: contents` above beats the UA `[hidden] { display: none }`, so
+      // a page hidden through the DOM `hidden` property would keep rendering
+      // its groups while the search (which reads the same flag) had already
+      // dropped it from the corpus.
+      &[hidden] {
+        display: none;
+      }
+    }
   }
 }

package/scss/_progress_bar.scss

@@ -0,0 +1,161 @@
+// _progress_bar.scss — <adw-progress-bar>, the determinate partner to
+// <adw-spinner>.
+//
+// TWO SOURCES, AND WHICH HALF CAME FROM WHICH — the two disagree, so this is not
+// bookkeeping:
+//
+//   GEOMETRY + COLOUR + THE OSD VARIANT come from
+//   `refs/libadwaita/src/stylesheet/widgets/_progress-bar.scss`: an 8px trough
+//   (:6), the 99px `$_progress-radius` (:33-35), the `%scale_trough` /
+//   `%scale_highlight` placeholders it shares with the scale
+//   (`_scale.scss:1-17`), the `> trough.empty > progress { all: unset }` rule
+//   that makes a zero fraction draw NOTHING rather than a 0px sliver (:85), and
+//   the `.osd` variant — a 2px bar with no trough, for under a header bar
+//   (:59-83).
+//
+//   THE INDETERMINATE ANIMATION comes from
+//   `refs/adwaita-web/adwaita-web/scss/_progressbar.scss:25-66`, because
+//   libadwaita has NO CSS equivalent: GTK animates a pulsing block from C
+//   (`gtk_progress_bar_pulse`), so the stylesheet has nothing to copy. Its
+//   keyframes and its `prefers-reduced-motion` fallback are the only parts taken
+//   from there. Its GEOMETRY is NOT: it draws a 6px bar with a 3px radius and
+//   has no trough placeholder, no OSD variant and no text node, so copying its
+//   numbers would put a bar in this package that matches neither source.
+//
+// NOT PORTED, deliberately: `progressbar.vertical` (:10-15) and the four
+// `progress.{left,right,top,bottom}` corner-radius rules (:37-55). Both exist
+// for orientations and trough-splitting `<adw-progress-bar>` does not expose —
+// there is no `orientation` attribute — and a rule nothing can ever select is a
+// rule that rots.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_progress-bar.scss:5-6,17-21,23-25,27-35,59-85
+// Reference: refs/libadwaita/src/stylesheet/_scale.scss:1-17 (%scale_trough, %scale_highlight)
+// Reference: refs/libadwaita/src/stylesheet/_colors.scss:280-286 (the trough colours)
+// Reference: refs/adwaita-web/adwaita-web/scss/_progressbar.scss:25-66 (indeterminate keyframes + reduced-motion fallback ONLY)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Copyright (c) 2025 csm (adwaita-web). MIT License.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+// `.dimmed` / `.numeric`, which the text node @extends exactly as upstream does.
+@use 'labels';
+
+adw-progress-bar {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+  // `progressbar.horizontal > trough { min-width: 150px }` (:5) is a WIDGET
+  // minimum in GTK, so it belongs on the element rather than on the trough.
+  min-width: 150px;
+
+  .adw-progress-bar-trough {
+    // %scale_trough (_scale.scss:1-10)
+    position: relative;
+    display: flex;
+    overflow: hidden;
+    height: 8px; // :6 — `&, > progress { min-height: 8px }`
+    border-radius: 99px;
+    background-color: color-mix(in srgb, currentColor 15%, transparent);
+    transition: background 200ms ease-out;
+
+    @media (prefers-contrast: more) {
+      // $trough_color_hc (_colors.scss:284)
+      background-color: color-mix(in srgb, currentColor 30%, transparent);
+    }
+  }
+
+  .adw-progress-bar-progress {
+    // %scale_highlight (_scale.scss:12-17) + $_progress-radius (:33-35)
+    height: 100%;
+    border-radius: 99px;
+    background-color: var(--accent-bg-color);
+    color: var(--accent-fg-color);
+    transition:
+      width 200ms ease-out,
+      background 200ms ease-out;
+  }
+
+  // `> text { @extend .dimmed; @extend .numeric; font-size: smaller; }` (:17-21)
+  // — literally upstream's three lines, now that `.dimmed` and `.numeric` exist
+  // here as the same utility classes they are there.
+  .adw-progress-bar-text {
+    @extend .dimmed;
+    @extend .numeric;
+
+    font-size: smaller;
+  }
+
+  // `&:disabled { filter: Opacity(var(--disabled-opacity)) }` (:23-25). This
+  // package defines no `--disabled-opacity`, so `--dim-opacity` stands in — the
+  // same substitution `_switch.scss` documents, not a fourth invented token.
+  &[disabled] {
+    opacity: var(--dim-opacity);
+  }
+
+  // Fill from the far end. GTK spells this `:inverted`; flexbox handles the
+  // writing direction, so nothing here needs an RTL branch.
+  &[inverted] .adw-progress-bar-trough {
+    justify-content: flex-end;
+  }
+
+  // `> trough.empty > progress { all: unset }` (:85) — at fraction 0 the
+  // indicator DISAPPEARS instead of drawing a rounded 0px stub.
+  .adw-progress-bar-trough.empty .adw-progress-bar-progress {
+    all: unset;
+  }
+
+  // The `.osd` variant (:59-83): a hairline bar with no trough at all, the way
+  // it is drawn under a header bar.
+  &[osd] {
+    min-width: 2px;
+
+    .adw-progress-bar-trough {
+      height: 2px;
+      border-radius: 0;
+      background-color: transparent;
+      box-shadow: none;
+    }
+
+    .adw-progress-bar-progress {
+      border-radius: 0;
+    }
+  }
+
+  // Indeterminate. The block leaves the flex flow and bounces across the trough;
+  // this is the ONLY part of the widget taken from the vendored web port, since
+  // GTK pulses from C and its stylesheet has no equivalent to copy.
+  &[pulsing] .adw-progress-bar-progress {
+    position: absolute;
+    inset-block: 0;
+    width: 30%;
+    animation: adw-progress-bar-indeterminate 1.5s infinite ease-in-out;
+
+    // `_progressbar.scss:42-49` — with motion suppressed the block stops moving
+    // and fills the trough, so the bar still reads as "busy" and not as "0%".
+    @media (prefers-reduced-motion: reduce) {
+      left: 0;
+      width: 100%;
+      animation: none;
+    }
+  }
+}
+
+// refs/adwaita-web/adwaita-web/scss/_progressbar.scss:53-66, verbatim offsets.
+// `left` rather than `inset-inline-start`: the port animates a physical offset,
+// and a keyframe that flipped with the writing direction would no longer be the
+// animation being cited.
+@keyframes adw-progress-bar-indeterminate {
+  0% {
+    left: -35%;
+    width: 30%;
+  }
+
+  50% {
+    left: 50%;
+    width: 40%;
+  }
+
+  100% {
+    left: 105%;
+    width: 30%;
+  }
+}

package/scss/_reset.scss

@@ -17,20 +17,31 @@
 // inherited typography + a host `* {}` box-sizing reset, which is what this
 // neutralises.
 
-// Every custom element adwaita-web defines. Keep in sync with
-// `src/elements/*` (the `customElements.define('adw-…')` calls).
+// Every custom element adwaita-web defines — one entry per `customElements
+// .define('adw-…')` call under `src/`.
+//
+// DERIVED, NOT REMEMBERED: `scripts/check-adwaita-reset-components.mjs` walks
+// those calls and fails on any tag missing from this list (and on any entry with
+// no call behind it). A hand-kept list is a second copy of the registry, and it
+// had already drifted — `adw-source-view` was defined for its whole life and
+// never listed, so it silently ran without the isolation floor. Nothing noticed,
+// because the only spec touching this file instantiates `adw-switch-row`.
 $adw-components:
   adw-about-dialog, adw-action-row, adw-alert-dialog, adw-alert-response,
   adw-avatar, adw-banner, adw-bottom-sheet, adw-bottom-sheet-content,
   adw-bottom-sheet-sheet, adw-button, adw-button-content, adw-button-row,
   adw-card, adw-carousel, adw-carousel-indicator-dots,
-  adw-carousel-indicator-lines, adw-clamp, adw-combo-row, adw-data-grid,
+  adw-carousel-indicator-lines, adw-checkbox, adw-clamp, adw-combo-row,
+  adw-data-grid,
   adw-dialog, adw-drop-down, adw-entry, adw-entry-row, adw-expander-row,
-  adw-header-bar, adw-inline-view-switcher, adw-menu-button, adw-navigation-page,
+  adw-header-bar, adw-icon, adw-inline-view-switcher, adw-menu-button,
+  adw-navigation-page,
   adw-navigation-split-view, adw-navigation-view, adw-overlay-split-view,
-  adw-password-entry-row, adw-preferences-dialog, adw-preferences-group,
-  adw-preferences-page, adw-sidebar, adw-sidebar-item, adw-sidebar-section,
-  adw-spinner, adw-spin-row, adw-split-button, adw-status-page, adw-switch-row,
+  adw-password-entry-row, adw-popover, adw-preferences-dialog,
+  adw-preferences-group, adw-preferences-page, adw-progress-bar, adw-radio,
+  adw-sidebar, adw-sidebar-item,
+  adw-sidebar-section, adw-source-view, adw-spinner, adw-spin-row,
+  adw-split-button, adw-status-page, adw-switch, adw-switch-row,
   adw-tab-page, adw-tab-view, adw-toast-overlay, adw-toggle, adw-toggle-group,
   adw-toolbar-view, adw-view-stack, adw-view-stack-page, adw-view-switcher,
   adw-view-switcher-bar, adw-view-switcher-page, adw-window, adw-window-title,

package/scss/_spinner.scss

@@ -1,28 +1,46 @@
-// _spinner.scss — adw-spinner styling (ring with a spinning arc).
+// _spinner.scss — adw-spinner styling.
+//
+// Almost nothing is left here on purpose. The ring is an SVG the element draws
+// per frame from `@gjsify/adwaita-core`'s `spinnerArc`, because the arc BREATHES
+// (2.7 to 102.8 degrees) and CSS cannot express that: the `border-top-color`
+// chase this file used to carry was a fixed 90-degree quarter-circle at 0.8s
+// against libadwaita's 1.2s, with a hardcoded grey track and square-cut ends.
+//
+// What CSS still owns is the box: the element is `size × size` and the ring is
+// centred inside it, which is how a 200px spinner shows a 64px ring
+// (adw-spinner.c:95-99 hands the widget's real size to the paintable, which caps
+// only the radius).
+//
+// There is deliberately NO `prefers-reduced-motion` rule. The C opts out of the
+// animation setting explicitly (`adw_animation_set_follow_enable_animations_setting
+// (…, FALSE)`, adw-spinner-paintable.c:537) — a frozen busy indicator reads as a
+// hang. This file used to stop the animation there.
+//
+// Reference: refs/libadwaita/src/adw-spinner.c
+// Reference: refs/libadwaita/src/adw-spinner-paintable.c
 // Reference: refs/adwaita-web/adwaita-web/scss/_spinner.scss
-// Reference: refs/libadwaita (Adw.Spinner)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Adapted for @gjsify/adwaita-web Web Components.
 
 adw-spinner {
-  display: inline-block;
+  // The element writes the measured box onto `style` when it upgrades; these are
+  // the values in force until then, which are Adwaita's own minimum
+  // (adw-spinner.c:14, reported as both minimum and natural at :78-81).
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   box-sizing: border-box;
-  width: 24px;
-  height: 24px;
-  // Neutral arc (currentColor, theme-aware) over a faint track — Adw.Spinner
-  // is a neutral indicator, NOT accent-coloured.
-  border: 3px solid rgba(127, 127, 127, 0.25);
-  border-top-color: currentColor;
-  border-radius: 50%;
-  animation: adw-spinner-spin 0.8s linear infinite;
+  width: 16px;
+  height: 16px;
+  // The arc strokes `currentColor` — `gtk_widget_get_color` (:432), the widget's
+  // TEXT colour, never the accent. The track is the same colour at 15%, which
+  // the SVG applies as `stroke-opacity`.
+  color: inherit;
 
-  @media (prefers-reduced-motion: reduce) {
-    animation: none;
-  }
-}
-
-@keyframes adw-spinner-spin {
-  to {
-    transform: rotate(360deg);
+  svg {
+    display: block;
+    // The ring never grows past its own diameter, so an over-large box centres
+    // it rather than stretching it.
+    flex: none;
   }
 }

package/scss/_split_button.scss

@@ -111,56 +111,12 @@
     }
   }
 
-  // --- Dropdown menu (popover) ---
-  .adw-split-button-menu {
-    position: absolute;
-    top: calc(100% + 4px);
-    right: 0;
-    z-index: 10;
-    display: flex;
-    flex-direction: column;
-    min-width: 160px;
-    padding: var(--spacing-xs);
-    border-radius: var(--button-radius);
-    background-color: var(--popover-bg-color, var(--window-bg-color, #fff));
-    color: var(--window-fg-color);
-    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2), 0 0 0 1px var(--separator-color);
-
-    &[hidden] {
-      display: none;
-    }
-  }
-
-  .adw-split-button-menu-item {
-    box-sizing: border-box;
-    display: flex;
-    align-items: center;
-    width: 100%;
-    min-height: 32px;
-    margin: 0;
-    padding: var(--spacing-xs) var(--spacing-s);
-    border: none;
-    border-radius: calc(var(--button-radius) - 2px);
-    background-color: transparent;
-    color: inherit;
-    font: inherit;
-    text-align: start;
-    cursor: pointer;
-    transition: background-color 0.1s ease;
-
-    &:hover {
-      background-color: var(--button-hover-color);
-    }
-
-    &:active {
-      background-color: var(--button-active-color);
-    }
-
-    &:focus-visible {
-      outline: 2px solid var(--accent-color);
-      outline-offset: -2px;
-    }
-  }
+  // The dropdown menu is `<adw-popover>` (`_popover.scss`), and this was the
+  // WORST of the three hand-rolled surfaces: `--button-radius` (9px) where
+  // libadwaita's popover is 15px, under a two-layer shadow that exists nowhere
+  // in the vendored stylesheet (`popover > contents` has three,
+  // _popovers.scss:18-20), and a `calc(var(--button-radius) - 2px)` (7px) row
+  // where `modelbutton` is 9px. Nothing element-specific was left to keep.
 
   // --- Suggested action — accent-coloured whole control ---
   &.suggested-action {

package/scss/_switch.scss

@@ -0,0 +1,90 @@
+// _switch.scss — the <adw-switch> control: a track, a hidden checkbox and a
+// sliding knob. UNSCOPED, which is the whole point of the partial.
+//
+// WHY IT IS ITS OWN FILE. These rules used to live inside `_switch_row.scss`,
+// nested under `adw-switch-row { … }` — so `.adw-switch` did not exist anywhere
+// else, and the moment a second widget needed a toggle it could not use it.
+// `_expander_row.scss` therefore carried a character-for-character copy of the
+// whole block (same 44×24 box, same hidden input, same 20px knob, same
+// `translateX(20px)`, same focus ring) under a different class name. Two copies
+// of a control is how a hover state gets fixed in one of them.
+//
+// FIDELITY, RECORDED RATHER THAN "FIXED": the 44×24 track with the 20px knob is
+// `refs/adwaita-web/adwaita-web/scss/_switch.scss`'s geometry, NOT libadwaita's.
+// libadwaita draws `switch` as a 3px-padded trough around a 20px slider with
+// `border-radius: 14px` (refs/libadwaita/src/stylesheet/widgets/_switch.scss:3-4,
+// :24-26) — about 26px tall, not 24, and correspondingly narrower. What ships
+// here is the vendored web port's box, unchanged by the extraction; changing the
+// geometry is a visual decision for a separate change, and citing libadwaita for
+// numbers that came from somewhere else would be the misreading the conformance
+// header warns about.
+//
+// Reference: refs/adwaita-web/adwaita-web/scss/_switch.scss (the geometry that ships)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_switch.scss:3-4,20-26 (the geometry that does not, + the disabled treatment)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Copyright (c) 2025 csm (adwaita-web). MIT License.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components; lifted out of
+//   `adw-switch-row {}` so <adw-switch> is usable anywhere.
+
+.adw-switch {
+  position: relative;
+  display: inline-block;
+  width: 44px;
+  height: 24px;
+  flex-shrink: 0;
+
+  // The real control: focusable and keyboard-toggleable, but never painted —
+  // the slider below is what the user sees and clicks.
+  input {
+    opacity: 0;
+    width: 0;
+    height: 0;
+    position: absolute;
+  }
+}
+
+.adw-switch-slider {
+  position: absolute;
+  cursor: pointer;
+  inset: 0;
+  background-color: var(--switch-off-bg);
+  border-radius: 12px;
+  transition: background-color 0.15s ease-out;
+
+  &::before {
+    content: "";
+    position: absolute;
+    height: 20px;
+    width: 20px;
+    left: 2px;
+    bottom: 2px;
+    background-color: var(--switch-knob-bg);
+    border-radius: 50%;
+    transition: transform 0.15s ease-out;
+    box-shadow: 0 1px 2px rgb(0 0 0 / 20%);
+  }
+}
+
+.adw-switch input:checked + .adw-switch-slider {
+  background-color: var(--accent-bg-color);
+
+  &::before {
+    transform: translateX(20px);
+  }
+}
+
+.adw-switch input:focus-visible + .adw-switch-slider {
+  outline: 2px solid var(--accent-color);
+  outline-offset: 2px;
+}
+
+// libadwaita dims the whole widget (`filter: Opacity(var(--disabled-opacity))`,
+// _switch.scss:20-22). This package has no `--disabled-opacity` token, so the
+// existing `--dim-opacity` stands in rather than a fourth invented colour.
+.adw-switch.disabled {
+  opacity: var(--dim-opacity);
+
+  .adw-switch-slider {
+    cursor: not-allowed;
+  }
+}