@gjsify/adwaita-web 0.53.0 → 0.55.0

package/lib/types/tab-chip.d.ts

@@ -0,0 +1,73 @@
+import type { AdwTabPageState } from '@gjsify/adwaita-core';
+import { type GtkImage } from './elements/gtk-image.js';
+export type AdwTabBarPage = AdwTabPageState<HTMLElement>;
+/** `SPACING`: the slack `scroll_to_tab_full` allows before it scrolls (adw-tab-box.c:24). */
+export declare const TAB_SPACING = 5;
+/** The five nodes of one chip, held so a caller can refresh one without re-querying it. */
+export interface TabChip {
+    /** The button itself: `role="tab"`, carrying `data-page-id`. */
+    el: HTMLButtonElement;
+    icon: GtkImage;
+    spinner: HTMLElement;
+    label: HTMLElement;
+    indicator: GtkImage;
+    close: HTMLButtonElement;
+}
+/** What the chip asks its bar for; the bar owns the model and the page list. */
+export interface TabChipHooks {
+    /** The chip was pressed — libadwaita's `select_page`. */
+    onSelect: () => void;
+    /** The close affordance was pressed; `AdwTab`'s own button, which stops propagation. */
+    onClose: () => void;
+    /** Pointer in or out of the chip, for `update_visible`'s `hovering` term. */
+    onHover: (hovering: boolean) => void;
+}
+/**
+ * One chip, node for node: the icon, the spinner that replaces it while the page is
+ * loading, the title, the attention indicator and the close affordance — in that order,
+ * because `AdwTab`'s template puts the close button LAST and the indicator before it.
+ */
+export declare const createTabChip: (hooks: TabChipHooks) => TabChip;
+/**
+ * `update_icons`, `update_title` and `update_needs_attention` — everything about a chip
+ * that reads off its PAGE rather than off the bar. The bar keeps the geometry half
+ * ({@link refreshTabChipClose}) to itself, because that is measured against ITS scroll
+ * window and only it knows where the chip sits in it.
+ */
+export declare const refreshTabChip: (chip: TabChip, page: AdwTabBarPage, defaultIcon: string | null) => void;
+/**
+ * `get_tab_position` in the BAR's scroll space: how far the chip sits from the strip's
+ * scroll origin, the one coordinate both `scroll_to_tab_full` and `update_visible` compare
+ * against the adjustment.
+ *
+ * Never `offsetLeft`. Nothing in a tab bar is positioned, so a chip's offsetParent is
+ * whichever positioned ancestor the HOST page happens to have; a bar that merely sits
+ * indented then measured every chip against the wrong origin and reported all of them
+ * clipped.
+ */
+export declare const chipPosition: (bar: HTMLElement, chip: HTMLElement) => number;
+/**
+ * `update_visible` (adw-tab-box.c:769-797) as libadwaita applies it, with the pinned gate
+ * from `AdwTab` folded in: `(hovering && fullyVisible) || selected`, never on a pinned tab.
+ *
+ * `dragging` is constantly false — tab drag-and-drop is compositor work and is not modelled
+ * — and the SPACING slack C also demands is deliberately NOT transplanted, because it is not
+ * slack there either: the allocation loop starts the first tab at `pos = SPACING` and puts
+ * SPACING between tabs (:3270-3286), so `pos - SPACING >= value` is exactly "flush against
+ * the leading edge". A strip without those gaps would report the first chip clipped.
+ */
+export declare const refreshTabChipClose: (bar: HTMLElement, chip: TabChip, page: AdwTabBarPage, state: {
+    hovering: boolean;
+    selected: boolean;
+}) => void;
+/**
+ * `scroll_to_tab_full` (adw-tab-box.c:928-961): bring the chip inside the BAR's own scroll
+ * window, padded by half of whichever is smaller, the chip or the leftover.
+ *
+ * The bar is the only thing C ever scrolls for a tab — `scroll_to_tab_full` writes
+ * `self->adjustment`, the strip's own adjustment, and nothing else. The DOM has no such
+ * narrow API: `focus()` and `scrollIntoView()` both walk EVERY scrollable ancestor up to
+ * the window. So this moves `scrollLeft` by hand, and the caller passes `preventScroll` to
+ * `focus()`.
+ */
+export declare const scrollChipIntoBar: (bar: HTMLElement, chip: HTMLElement) => void;

package/lib/types/template-classes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Registers the custom element `tag` as the class a `.blp` means by `$name`, spelled as the
+ * file spells it (`SourceView` for `$SourceView`). The element builds its own internals,
+ * typically from its own `.blp?shared-tree`, and must be defined by the time a tree uses it.
+ *
+ * Registering the same pair again is a no-op; a different tag under the same name is refused,
+ * as `Gtk.Builder` refuses a type registered twice.
+ */
+export declare function registerTemplateClass(name: string, tag: string): void;
+/** The tag `name` was registered under, or a refusal that names what is missing. */
+export declare function templateTagFor(name: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.53.0",
+    "version": "0.55.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -18,6 +18,10 @@
             "types": "./lib/types/fonts.d.ts",
             "default": "./src/fonts.ts"
         },
+        "./capabilities": {
+            "types": "./src/capabilities.d.mts",
+            "default": "./src/capabilities.mjs"
+        },
         "./style.css": {
             "types": "./style.css.d.ts",
             "default": "./dist/adwaita-web.css"
@@ -45,16 +49,16 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.53.0",
-        "@gjsify/adwaita-fonts": "^0.53.0",
-        "@gjsify/adwaita-icons": "^0.53.0",
+        "@gjsify/adwaita-core": "^0.55.0",
+        "@gjsify/adwaita-fonts": "^0.55.0",
+        "@gjsify/adwaita-icons": "^0.55.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/blueprint": "^0.53.0",
-        "@gjsify/cli": "^0.53.0",
-        "@gjsify/unit": "^0.53.0",
-        "@gjsify/vite-plugin-blueprint": "^0.53.0",
+        "@gjsify/blueprint": "^0.55.0",
+        "@gjsify/cli": "^0.55.0",
+        "@gjsify/unit": "^0.55.0",
+        "@gjsify/vite-plugin-blueprint": "^0.55.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_action_row.scss

@@ -9,8 +9,8 @@ adw-action-row {
   display: flex;
   align-items: center;
   gap: var(--spacing-m);
-  min-height: 50px;
-  padding: var(--spacing-s) var(--spacing-m);
+  min-height: 54px;
+  padding: 0 var(--spacing-m);
   border-bottom: 1px solid var(--card-shade-color);
   color: var(--card-fg-color);
 

package/scss/_application_window.scss

@@ -0,0 +1,26 @@
+// _application_window.scss — the application window's menubar strip.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_toolbars.scss (`menubar`, the
+//   row libadwaita styles for GtkPopoverMenuBar — the GTK 4 menubar this widget
+//   stands in for)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_header-bar.scss (the bar it sits
+//   above, for the background and the border between them)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+
+// Modifications: Implemented for @gjsify/adwaita-web Web Components.
+
+.adw-application-window-menubar {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 2px;
+  padding: 0 6px;
+  background-color: var(--headerbar-bg-color);
+  color: var(--headerbar-fg-color);
+  // The rule between the bar and the header bar below it, which is the whole of what
+  // separates one bar from another in a stacked window.
+  box-shadow: inset 0 -1px 0 var(--headerbar-border-color);
+
+  &[hidden] {
+    display: none;
+  }
+}

package/scss/_aspect_frame.scss

@@ -0,0 +1,25 @@
+// _aspect_frame.scss — <gtk-aspect-frame>: draws NOTHING, it only sizes and places.
+//
+// libadwaita has no rule for the `aspectframe` node (its stylesheet never names it), and
+// neither should this: the widget paints no border, no background and no frame, because
+// `gtk_aspect_frame_size_allocate` gives its child one allocation of the requested shape
+// and puts that box at (`xalign`, `yalign`) — gtakaspectframe.c:561-587. That allocation
+// IS the widget.
+//
+// What is left to CSS is the placing, and all of it is per-INSTANCE: the element writes
+// `justify-content` and `align-items` from `xalign` / `yalign` and the child's
+// `aspect-ratio`, `max-width` and `max-height` inline, because a stylesheet cannot key on a
+// fraction. So this partial is the flex container and nothing else.
+//
+// Reference: refs/gtk/gtk/gtkaspectframe.c:561-587
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+gtk-aspect-frame {
+  display: flex;
+  // The child's shape and both alignments are written INLINE by the element, because a
+  // stylesheet cannot key on a fraction; these are the values in the frame before it does,
+  // which are also the pspec defaults for `xalign` and `yalign`.
+  justify-content: center;
+  align-items: center;
+}

package/scss/_bin.scss

@@ -0,0 +1,26 @@
+// _bin.scss — <adw-bin>, the one-child container.
+//
+// libadwaita has NO `bin` node: `adw_bin_class_init` sets no CSS name and the
+// stylesheet never mentions one (the widget's whole rule is the layout manager, and
+// `GtkBinLayout` gives the child the widget's entire allocation). So the only rule here
+// is the block box that allocation needs, and the one cross-axis stretch that says
+// "the child fills the bin" — a `GtkBinLayout` gives its child the bin's height too,
+// which a block child would otherwise size to its own content.
+//
+// Reference: refs/libadwaita/src/adw-bin.c:123 (GtkBinLayout)
+// Reference: refs/gtk/gtk/gtkbinlayout.c:81 (`gtk_bin_layout_allocate` hands the child the
+//   allocation on both axes)
+// Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+adw-bin {
+  display: block;
+
+  // One child, and it fills — `gtk_bin_layout_allocate` allocates the whole widget to
+  // its single child. `:only-child` rather than `> *` because a bin keeps ONE
+  // (`adw_bin_set_child` unparents the one it replaces), so the case where the selector
+  // could match two is one the element has already refused.
+  > :only-child {
+    block-size: 100%;
+  }
+}

package/scss/_button.scss

@@ -177,6 +177,51 @@ gtk-button {
       background-color: color-mix(in srgb, black calc(0.75 * 65%), currentColor calc(0.25 * 65%));
     }
   }
+
+  // Checked — `<gtk-toggle-button>`'s pressed state, libadwaita's `:checked`
+  // (_buttons.scss:44-56, 136-140, 169-177, 199-210). Last in the block so it outranks the
+  // hover/active/`.raised` rules of equal specificity above, which is also why the flat,
+  // suggested and destructive variants restate their own checked colours: upstream
+  // resolves them by the same source order.
+  &.checked {
+    background-color: color-mix(in srgb, currentColor 30%, transparent);
+
+    &:hover {
+      background-color: color-mix(in srgb, currentColor 35%, transparent);
+    }
+
+    &:active {
+      background-color: color-mix(in srgb, currentColor 40%, transparent);
+    }
+  }
+
+  &.flat.checked {
+    background-color: color-mix(in srgb, currentColor 10%, transparent);
+
+    &:hover {
+      background-color: color-mix(in srgb, currentColor 13%, transparent);
+    }
+
+    &:active {
+      background-color: color-mix(in srgb, currentColor 19%, transparent);
+    }
+  }
+
+  &.suggested-action.checked {
+    background-color: var(--accent-bg-color);
+  }
+
+  &.destructive-action.checked {
+    background-color: color-mix(in srgb, currentColor 35%, transparent);
+
+    &:hover {
+      background-color: color-mix(in srgb, currentColor 40%, transparent);
+    }
+
+    &:active {
+      background-color: color-mix(in srgb, currentColor 45%, transparent);
+    }
+  }
 }
 
 // The symbolic icon (`.adw-icon`) used to be declared here, because the first

package/scss/_calendar.scss

@@ -0,0 +1,176 @@
+// _calendar.scss — <gtk-calendar>: the `calendar` node, its header, and the grid of
+// `day-name` / `week-number` / `day-number` labels.
+//
+// libadwaita's block is 58 lines and almost all of it is state: `:checked` for a MARKED day,
+// `:selected` for the SELECTED one, `.today` for today's, `.other-month` for the spill. The
+// port spells those as four classes off one element — `gtk-calendar.ts` raises the same four
+// widget state flags `calendar_update_day_labels` does (gtkcalendar.c:1015-1046) — and the
+// selectors below are the same four, in the same specificity order, so the cascade resolves
+// the way the C's stylesheet resolves it.
+//
+// THE CASCADE ORDER MATTERS and it is why the rules are not merged: `label.today` sets an
+// inset box-shadow and then CANCELS it under `:selected` (_calendar.scss:24-30), and
+// `.day-number:checked` sets a 30% accent tint that `:selected` then replaces with the solid
+// accent (_calendar.scss:37-51). A merged rule that applied `:checked` last would tint the
+// selected day, which is exactly what upstream avoids.
+//
+// `font-variant-numeric: tabular-nums` is the load-bearing line for a grid of day numbers: the
+// column widths come from the widest number, and proportional digits would make 1 narrower than
+// 8 and the whole grid breathe as the month changes.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_calendar.scss:1-58
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+gtk-calendar {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  color: var(--view-fg-color);
+  background-color: var(--view-bg-color);
+  background-clip: padding-box;
+  // `calendar { border: 1px solid $border_color }` (_calendar.scss:4).
+  border: 1px solid var(--border-color);
+  border-radius: var(--window-radius);
+  font-variant-numeric: tabular-nums;
+
+  &.view:disabled {
+    color: var(--view-fg-color);
+  }
+}
+
+.adw-calendar-header {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 4px;
+  // `> header { border-bottom: 1px solid $border_color }` (_calendar.scss:12).
+  border-bottom: 1px solid var(--border-color);
+}
+
+.adw-calendar-month {
+  font-weight: bold;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.adw-calendar-year {
+  // The C measures the year label once and adds 10px so "changing the year does not increase
+  // the calendar width" (gtkcalendar.c:853-858) — a fixed slot is the same promise.
+  flex: 0 0 auto;
+  font-weight: bold;
+}
+
+.adw-calendar-nav-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 auto;
+  // `@extend %button_basic_flat` with `border-radius: 0` (_calendar.scss:15-16).
+  border-radius: 0;
+
+  &[disabled] {
+    opacity: var(--disabled-opacity);
+  }
+}
+
+.adw-calendar-grid {
+  display: grid;
+  // Column 0 is the week-number column upstream (gtkcalendar.c:786-790), and it exists whether
+  // or not the numbers are shown, so the day names and the days line up under it either way.
+  grid-template-columns: auto repeat(7, 1fr);
+  // `> grid { padding-left: 3px; padding-bottom: 3px }` (_calendar.scss:21-22).
+  padding: 3px 0 3px 3px;
+}
+
+.adw-calendar-day-name,
+.adw-calendar-week-number,
+.adw-calendar-week-spacer {
+  // `margin-top: 3px; margin-right: 3px` (_calendar.scss:34-35), applied to the labels.
+  margin-top: 3px;
+  margin-right: 3px;
+  font-size: var(--font-size-small);
+  opacity: var(--dim-opacity);
+  text-align: center;
+}
+
+.adw-calendar-week-number,
+.adw-calendar-week-spacer {
+  // The week-number column is the day names' share of a cell: a number is narrower than a name,
+  // and letting it size itself would make the grid jitter between a wide and a narrow month.
+  max-width: 2.5em;
+}
+
+.adw-calendar-cell {
+  // `> label { margin-top: 3px; margin-right: 3px }` and `.day-number { padding: 3px }`
+  // (_calendar.scss:32-38).
+  margin-top: 3px;
+  margin-right: 3px;
+  padding: 3px;
+  border: none;
+  border-radius: 0;
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-variant-numeric: inherit;
+  line-height: 1;
+  text-align: center;
+  cursor: pointer;
+
+  &:hover {
+    background-color: color-mix(in srgb, currentColor 6%, transparent);
+  }
+
+  &:active {
+    background-color: color-mix(in srgb, currentColor 12%, transparent);
+  }
+
+  &:focus-visible,
+  &.focused {
+    // `@include focus-ring($focus-state: ':focus')` (_calendar.scss:33) — the C focuses the
+    // LABEL rather than the grid, which is what `.focused` is on this port.
+    outline: 2px solid var(--accent-color);
+    outline-offset: -2px;
+  }
+
+  // `:checked` — `background-color: color-mix(… var(--accent-bg-color) 30%, transparent)`
+  // (_calendar.scss:39-43), the MARKED day.
+  &.marked {
+    border-radius: var(--button-radius);
+    background-color: color-mix(in srgb, var(--accent-bg-color) 30%, transparent);
+  }
+
+  // `:selected { background-color: var(--accent-bg-color); color: var(--accent-fg-color) }`
+  // (_calendar.scss:45-50), and it comes AFTER `:checked` so the selected day is not tinted.
+  &.selected {
+    border-radius: var(--button-radius);
+    background-color: var(--accent-bg-color);
+    color: var(--accent-fg-color);
+  }
+
+  // `.other-month { color: color-mix(in srgb, currentColor 30%, transparent) }`
+  // (_calendar.scss:53-55), the leading and trailing spill.
+  &.other-month {
+    color: color-mix(in srgb, currentColor 30%, transparent);
+  }
+
+  // `label.today { box-shadow: inset 0 0 0 -2px $border_color }` (_calendar.scss:24-25) — an
+  // inset rule, not a border, so it does not change the cell's size.
+  &.today {
+    box-shadow: inset 0 -2px var(--border-color);
+  }
+
+  // `label.today:selected { box-shadow: none }` (_calendar.scss:27-29): the selected day's
+  // accent fill IS the emphasis, so today's underline steps aside rather than doubling up.
+  &.today.selected {
+    box-shadow: none;
+  }
+
+  &[disabled] {
+    // `lower_limit_reached` / `upper_limit_reached` blank those cells and make them
+    // insensitive (gtkcalendar.c:1004-1015), so there is nothing to dim — just nothing.
+    background: none;
+    cursor: default;
+  }
+}

package/scss/_center_box.scss

@@ -0,0 +1,25 @@
+// _center_box.scss — <gtk-center-box>: three children, and the space between them.
+//
+// `gtk_center_box_set_css_name (widget_class, I_("box"))` (gtkcenterbox.c:345) means the
+// theme's `box` rule styles this widget, and libadwaita ships NO `box` rule — a box draws
+// nothing, it only places. `justify-content: space-between` IS the placement: the centre
+// layout puts the start child at the start, the end child at the end and the centre between
+// them, growing the centre into whatever is left when it expands
+// (gtkcenterlayout.c:174-186).
+//
+// The `shrink-center-last` weights and a `baseline-position` are written INLINE by the
+// element, because both are per-instance values a selector cannot express: the weights
+// differ per child, and the position is a fraction.
+//
+// Reference: refs/gtk/gtk/gtkcenterbox.c:345-346
+// Reference: refs/gtk/gtk/gtkcenterlayout.c:144-186
+// Copyright (c) The GTK Team. LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+gtk-center-box {
+  display: flex;
+  justify-content: space-between;
+  // A child's default `valign` is FILL, and the centre layout's one line takes the whole
+  // cross axis — the same thing `_box.scss` states for `<gtk-box>`.
+  align-items: stretch;
+}

package/scss/_checks.scss

@@ -103,7 +103,9 @@ adw-radio {
       display: block;
       width: 100%;
       height: 100%;
-      background-color: currentColor;
+      // Transparent until a state supplies a glyph: an unmasked currentColor box is a
+      // solid square, which is what an unchecked control used to paint.
+      background-color: transparent;
       mask-repeat: no-repeat;
       mask-position: center;
       mask-size: 14px; // -gtk-icon-size: 14px (:25)
@@ -187,11 +189,13 @@ adw-radio .adw-check-indicator {
 
 // `check:checked` → check.svg (:70) / `radio:checked` → bullet.svg (:76)
 gtk-check-button[checked] .adw-check-indicator::after {
+  background-color: currentColor;
   mask-image: $check-glyph;
   -webkit-mask-image: $check-glyph;
 }
 
 adw-radio[checked] .adw-check-indicator::after {
+  background-color: currentColor;
   mask-image: $bullet-glyph;
   -webkit-mask-image: $bullet-glyph;
 }
@@ -203,6 +207,7 @@ adw-radio[checked] .adw-check-indicator::after {
 // in `@gjsify/adwaita-core` encodes for the a11y value.
 gtk-check-button[indeterminate] .adw-check-indicator::after,
 adw-radio[indeterminate] .adw-check-indicator::after {
+  background-color: currentColor;
   mask-image: $dash-glyph;
   -webkit-mask-image: $dash-glyph;
 }

package/scss/_clamp_scrollable.scss

@@ -0,0 +1,28 @@
+// _clamp_scrollable.scss — <adw-clamp-scrollable>.
+//
+// The widget has NO node of its own: `adw_clamp_scrollable_class_init` ends with
+// `set_layout_manager_type(ADW_TYPE_CLAMP_LAYOUT)` and `set_css_name("clamp")`
+// (adw-clamp-scrollable.c:328-329), so it draws exactly what `<adw-clamp>` draws — which
+// is nothing, since there is no `clamp {}` block in the libadwaita stylesheet either. A
+// clamp measures; the cap and the `small`/`medium`/`large` classes are written onto the
+// CHILD by the element, out of `clampAllocate`.
+//
+// What this element adds is `overflow`. In C the CHILD is the `Gtk.Scrollable` and four
+// `g_object_bind_property` calls forward the adjustments onto it
+// (adw-clamp-scrollable.c:440-455); a DOM scrollport is the element itself, so the
+// scrolling moves one level up and the element writes `overflow-x`/`overflow-y` from
+// `hscroll-policy`/`vscroll-policy`. This rule is the floor for an author who set
+// neither policy — GTK's default is GTK_POLICY_AUTOMATIC, which shows a scrollbar only
+// when there is something to scroll, which is `auto` here.
+//
+// Reference: refs/libadwaita/src/adw-clamp-scrollable.c:328-329 (the `clamp` node)
+// Reference: refs/libadwaita/src/adw-clamp-layout.c (adw_clamp_layout_allocate — the
+//   size classes the element stamps on the child)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components; the scrollport is the
+//   element where C's is the child, for the reason the element's header records.
+
+adw-clamp-scrollable {
+  display: block;
+  overflow: auto;
+}

package/scss/_color_button.scss

@@ -0,0 +1,67 @@
+// _color_button.scss — `<gtk-color-dialog-button>`: the `button.color` node and the
+// swatch it holds.
+//
+// THE SWATCH IS NOT LIBADWAITA'S, and saying so is the point of this partial. GTK paints
+// the `GtkColorSwatch` from GTK's OWN theme — libadwaita's `_color-chooser.scss` styles the
+// `colorchooser` popover, and `grep` finds no rule for the swatch or for `colorbutton` at
+// all. So what upstream does have is this:
+//
+//   · the node `colorbutton > button.color` and the `.color` style class
+//     (gtkcolordialogbutton.c:63-70, :163) — which is what puts the button in the
+//     `.linked` group and makes it square;
+//
+// and what this partial adds is the geometry `gtk_color_dialog_button_init` asks for: a
+// swatch as wide as the word "Black" rendered at the base size and as tall as its line
+// (:139-148). 24x18 is that box at the base font size, so the button around it is the
+// usual 34px-tall button.
+//
+// THE TRANSLUCENT CLAUSE IS GTK's own drawing, keyed off the element's `data-translucent`:
+// `GtkColorSwatch` draws a checkerboard under a colour with alpha, and `rgba_to_gdk_rgba`
+// is how it decides. A browser has no such thing, and a translucent colour on a plain
+// background is unreadable without one.
+//
+// Reference: refs/gtk/gtk/gtkcolordialogbutton.c:63-70 (the node), :139-163 (the swatch,
+//   the `.color` class), :329-347 (the accessible name's rounding)
+// Reference: refs/libadwaita/src/stylesheet/widgets/_linked.scss:6 (`colorbutton > button`)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web — the swatch is a `<span>` painted with
+//   `background-color`, and its checkerboard is this package's drawing of GtkColorSwatch.
+
+gtk-color-dialog-button {
+  display: inline-flex;
+}
+
+.color-button-swatch {
+  display: block;
+  width: 24px;
+  height: 18px;
+  border-radius: 4px;
+  box-shadow: 0 0 0 1px var(--shade-color);
+  // The checkerboard, only while the colour is translucent — the element writes
+  // `data-translucent` from `rgba[3] < 1`, which is GtkColorSwatch's own test.
+  &[data-translucent='true'] {
+    background-image:
+      linear-gradient(45deg, rgb(0 0 6 / 12%) 25%, transparent 25%),
+      linear-gradient(-45deg, rgb(0 0 6 / 12%) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, rgb(0 0 6 / 12%) 75%),
+      linear-gradient(-45deg, transparent 75%, rgb(0 0 6 / 12%) 75%);
+    background-position:
+      0 0,
+      0 4px,
+      4px -4px,
+      -4px 0;
+    background-size: 8px 8px;
+  }
+}
+
+// The chooser itself: visually nothing, and reachable only from the button's click, which
+// is why it is `aria-hidden` and out of the tab order rather than merely transparent.
+.color-button-input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  border: none;
+  opacity: 0;
+  pointer-events: none;
+}