@gjsify/adwaita-web 0.53.0 → 0.55.0

package/src/tab-chip.ts

@@ -0,0 +1,200 @@
+// The tab chip — one button in an AdwTabBox — and the two measurements that hang off
+// it, shared by the two widgets that render one.
+//
+// WHY A SHARED MODULE. `<adw-tab-bar>` is libadwaita's tab bar as a widget of its own,
+// and `<adw-tab-view>` has carried a merged one since before that existed. Both draw the
+// SAME chip — the same five nodes in the same order, the same `.adw-tab-*` classes, the
+// same derivations from `@gjsify/adwaita-core` — so the markup lives here once and each
+// widget owns the parts that are genuinely its own: the bar the page list scrolls in, the
+// selection, and whether the strip is revealed at all.
+//
+// The two measurements are here for the reason `adw-tab-view.ts` used `offsetLeft` and
+// got it wrong: both are read in the BAR's scroll space, so both take the bar as an
+// argument instead of finding an offsetParent, and neither can be reused by a caller that
+// has a different strip.
+//
+// Reference: refs/libadwaita/src/adw-tab.c (the chip: title, icons, close button, pinned)
+// Reference: refs/libadwaita/src/adw-tab-box.c (SPACING, update_visible, scroll_to_tab_full)
+// Copyright (c) 2020-2022 Purism SPC / GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented for @gjsify/adwaita-web; the chip is a `<button>` and the
+// indicator nodes are `<gtk-image>`.
+
+import { tabCloseVisible, tabIconState, tabTooltip } from '@gjsify/adwaita-core';
+import type { AdwTabPageState } from '@gjsify/adwaita-core';
+
+import { type GtkImage, createGtkImage } 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 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 const createTabChip = (hooks: TabChipHooks): TabChip => {
+    const el = document.createElement('button');
+    el.type = 'button';
+    el.className = 'adw-tab';
+    el.setAttribute('role', 'tab');
+
+    // Decorative mask-image nodes — <gtk-image> carries the convention, including the
+    // `-symbolic` strip, which is ours and not C's: there the name reaches `GtkImage`
+    // untouched.
+    const icon = createGtkImage(null, 'adw-tab-icon');
+
+    // `AdwTabPage:loading` swaps the icon image for an `AdwSpinnerPaintable` — the SAME
+    // paintable `Adw.Spinner` uses (`update_icons`). So this is a real `<adw-spinner>` in
+    // the icon's slot, not a ring drawn again in CSS: a CSS copy inherits every spinner
+    // defect independently.
+    const spinner = document.createElement('adw-spinner');
+    spinner.className = 'adw-tab-spinner';
+    spinner.setAttribute('size', '16');
+    spinner.hidden = true;
+
+    const label = document.createElement('span');
+    label.className = 'adw-tab-title';
+
+    const indicator = createGtkImage(null, 'adw-tab-indicator');
+
+    // Close affordance — a small flat button drawn with a CSS "×" glyph. NOT because the
+    // glyph is unavailable: `window-close` is in the ICONS map and has a mask class. It is a
+    // SIZING difference — upstream's close button is 24px around a 16px symbolic
+    // (adw-tab.ui:77) and a 16px-grid symbolic scaled into a narrower chip is a design
+    // change, not a rename.
+    //
+    // C's `can-focus=False` is NOT set here, and that is where the roving obligation
+    // decides it: `scripts/check-adwaita-keyboard-contract.mjs` holds a negative tabindex
+    // against the file that registers the arrow keys behind it, and a builder shared by two
+    // bars registers none. Each widget sets `close.tabIndex` beside its own key handling.
+    const close = document.createElement('button');
+    close.type = 'button';
+    close.className = 'adw-tab-close';
+    close.setAttribute('aria-label', 'Close tab');
+    close.addEventListener('click', (event) => {
+        event.stopPropagation();
+        hooks.onClose();
+    });
+
+    el.append(icon, spinner, label, indicator, close);
+    el.addEventListener('click', () => hooks.onSelect());
+    el.addEventListener('pointerenter', () => hooks.onHover(true));
+    el.addEventListener('pointerleave', () => hooks.onHover(false));
+
+    return { el, icon, spinner, label, indicator, close };
+};
+
+/**
+ * `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 const refreshTabChip = (chip: TabChip, page: AdwTabBarPage, defaultIcon: string | null): void => {
+    chip.label.textContent = page.title;
+    // The tooltip is Pango MARKUP when the page sets one of its own. The DOM `title`
+    // attribute is a TEXT sink, so the markup is shown verbatim rather than pushed
+    // through an HTML sink — interpreting it would execute page-supplied markup.
+    chip.el.title = tabTooltip(page);
+    chip.el.classList.toggle('pinned', page.pinned);
+    chip.el.classList.toggle('needs-attention', page.needsAttention);
+    chip.el.classList.toggle('closing', page.closing);
+
+    const icons = tabIconState(page, defaultIcon);
+    chip.icon.iconName = icons.icon;
+    // The two occupy the same slot and are never both visible: C REPLACES the image's
+    // contents rather than stacking a second node.
+    chip.icon.hidden = !icons.iconVisible || icons.spinner;
+    // The spinner is mounted only while it spins, so an idle tab holds no element in the
+    // shared rAF ticker.
+    chip.spinner.hidden = !(icons.spinner && icons.iconVisible);
+    chip.indicator.iconName = page.indicatorIcon;
+    chip.indicator.hidden = !icons.indicatorVisible;
+};
+
+/**
+ * `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 const chipPosition = (bar: HTMLElement, chip: HTMLElement): number =>
+    chip.getBoundingClientRect().left - bar.getBoundingClientRect().left + bar.scrollLeft;
+
+/**
+ * `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 const refreshTabChipClose = (
+    bar: HTMLElement,
+    chip: TabChip,
+    page: AdwTabBarPage,
+    state: { hovering: boolean; selected: boolean },
+): void => {
+    const value = bar.scrollLeft;
+    const pos = chipPosition(bar, chip.el);
+    const fullyVisible = pos >= value && pos + chip.el.offsetWidth <= value + bar.clientWidth;
+    chip.close.hidden = !tabCloseVisible({
+        hovering: state.hovering,
+        fullyVisible,
+        selected: state.selected,
+        dragging: false,
+        pinned: page.pinned,
+    });
+};
+
+/**
+ * `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 const scrollChipIntoBar = (bar: HTMLElement, chip: HTMLElement): void => {
+    const pageSize = bar.clientWidth;
+    const width = chip.offsetWidth;
+    // Unmeasured (detached, or still inside connectedCallback): nothing to scroll to.
+    if (pageSize <= 0 || width <= 0) return;
+
+    const value = bar.scrollLeft;
+    const pos = chipPosition(bar, chip);
+    const padding = Math.min(width, pageSize - width) / 2;
+    if (pos - TAB_SPACING < value) bar.scrollLeft = pos - padding;
+    else if (pos + width + TAB_SPACING > value + pageSize) bar.scrollLeft = pos + width + padding - pageSize;
+};

package/src/template-classes.ts

@@ -0,0 +1,45 @@
+// The application's own classes, which a `.blp` names with a `$` (ADR 0093): `$SourceView`,
+// or `template $MainButton : Adw.Bin` defining one. `SharedTreeNode.extern` says the tag is
+// such a class, and this registry is where the shared-tree builder looks it up.
+//
+// The registry lives here and not in `@gjsify/adwaita-core` because the stored thing is the
+// renderer's own: the tag of a custom element the application defines. A name like `Display`
+// is not a valid custom-element name and no case rule can invent one, so the caller says which
+// tag the class answers to. The application defines the element itself
+// (through the custom element registry), which keeps this package's element set the one it ships.
+
+const registry = new Map<string, string>();
+
+/**
+ * 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 function registerTemplateClass(name: string, tag: string): void {
+    const known = registry.get(name);
+    if (known !== undefined && known !== tag) {
+        throw new Error(`the template class '${name}' is already registered as <${known}>.`);
+    }
+    registry.set(name, tag);
+}
+
+/** The tag `name` was registered under, or a refusal that names what is missing. */
+export function templateTagFor(name: string): string {
+    const tag = registry.get(name);
+    if (tag === undefined) {
+        throw new Error(
+            `the tree uses the class '$${name}', which no registerTemplateClass() call registered: ` +
+                'adwaita-web cannot build a class it does not know.',
+        );
+    }
+    if (customElements.get(tag) === undefined) {
+        throw new Error(
+            `the class '$${name}' is registered as <${tag}>, which nothing has defined in the custom element registry, so ` +
+                'the element would stay an empty unknown tag.',
+        );
+    }
+    return tag;
+}

package/src/test.browser.mts

@@ -23,10 +23,19 @@ import { AdwSplitViewsTest } from './split-views.spec.js';
 import { AdwButtonRowTest } from './adw-button-row.spec.js';
 import { AdwActionRowsTest } from './adw-action-rows.spec.js';
 import { AdwBreakpointsTest } from './breakpoints.spec.js';
+import { AdwBreakpointBinTest } from './adw-breakpoint-bin.spec.js';
+import { AdwMultiLayoutViewTest } from './adw-multi-layout-view.spec.js';
 import { AdwDataGridTest } from './adw-data-grid.spec.js';
 import { AdwDialogTest } from './adw-dialog.spec.js';
+import { AdwWindowTest } from './adw-window.spec.js';
+import { AdwShortcutsTest } from './adw-shortcuts.spec.js';
+import { AdwApplicationWindowTest } from './adw-application-window.spec.js';
 import { AdwAlertDialogTest } from './adw-alert-dialog.spec.js';
 import { GtkDropDownTest } from './gtk-drop-down.spec.js';
+import { GtkDragIconTest } from './gtk-drag-icon.spec.js';
+import { GtkDrawingAreaTest } from './gtk-drawing-area.spec.js';
+import { GtkGLAreaTest } from './gtk-gl-area.spec.js';
+import { GtkGraphicsOffloadTest } from './gtk-graphics-offload.spec.js';
 import { AdwRowStateTest } from './adw-row-state.spec.js';
 import { AdwTabViewTest } from './adw-tab-view.spec.js';
 import { AdwToastOverlayTest } from './adw-toast-overlay.spec.js';
@@ -36,9 +45,17 @@ import { AdwWrapBoxTest } from './adw-wrap-box.spec.js';
 import { AdwHeaderBarTest } from './adw-header-bar.spec.js';
 import { GtkEntryTest } from './gtk-entry.spec.js';
 import { GtkMenuButtonTest } from './gtk-menu-button.spec.js';
+import { GtkPopoverTest } from './gtk-popover.spec.js';
+import { GtkPopoverRoleTest } from './gtk-popover-role.spec.js';
+import { GtkPopoverBinTest } from './gtk-popover-bin.spec.js';
+import { GtkPopoverMenuTest } from './gtk-popover-menu.spec.js';
+import { GtkPopoverMenuBarTest } from './gtk-popover-menu-bar.spec.js';
 import { GioMenuTest } from './gio-menu.spec.js';
 import { GtkValueDoorsTest } from './gtk-value-doors.spec.js';
 import { GtkButtonTest } from './gtk-button.spec.js';
+import { GtkAboutDialogTest } from './gtk-about-dialog.spec.js';
+import { GtkEmojiChooserTest } from './gtk-emoji-chooser.spec.js';
+import { GtkPrintDialogsTest } from './gtk-print-dialogs.spec.js';
 import { AdwBannerTest } from './adw-banner.spec.js';
 import { AdwButtonContentTest } from './adw-button-content.spec.js';
 import { GtkImageTest } from './gtk-image.spec.js';
@@ -46,8 +63,68 @@ import { AdwIconRegistryTest } from './icon-registry.spec.js';
 import { GtkSwitchTest } from './gtk-switch.spec.js';
 import { AdwChecksTest } from './checks.spec.js';
 import { GtkProgressBarTest } from './gtk-progress-bar.spec.js';
+import { GtkLevelBarTest } from './gtk-level-bar.spec.js';
+import { GtkSpinnerTest } from './gtk-spinner.spec.js';
+import { GtkNotebookTest } from './gtk-notebook.spec.js';
+import { GtkStackTest } from './gtk-stack.spec.js';
+import { GtkStackSidebarTest } from './gtk-stack-sidebar.spec.js';
+import { GtkStackSwitcherTest } from './gtk-stack-switcher.spec.js';
+import { GtkColumnViewTest } from './gtk-column-view.spec.js';
+import { GtkGridViewTest } from './gtk-grid-view.spec.js';
+import { GtkListViewTest } from './gtk-list-view.spec.js';
+import { GtkHeaderBarTest } from './gtk-header-bar.spec.js';
+import { GtkWindowControlsTest } from './gtk-window-controls.spec.js';
+import { GtkWindowTest } from './gtk-window.spec.js';
+import { GtkApplicationWindowTest } from './gtk-application-window.spec.js';
+import { GtkActionBarTest } from './gtk-action-bar.spec.js';
+import { GtkSeparatorTest } from './gtk-separator.spec.js';
+import { GtkCalendarTest } from './gtk-calendar.spec.js';
+import { GtkFlowBoxTest } from './gtk-flow-box.spec.js';
+import { GtkListBoxTest } from './gtk-list-box.spec.js';
+import { GtkTreeExpanderTest } from './gtk-tree-expander.spec.js';
+import { GtkToggleButtonTest } from './gtk-toggle-button.spec.js';
+import { GtkExpanderTest } from './gtk-expander.spec.js';
+import { GtkOverlayTest } from './gtk-overlay.spec.js';
+import { GtkPanedTest } from './gtk-paned.spec.js';
+import { GtkRevealerTest } from './gtk-revealer.spec.js';
+import { GtkScaleTest } from './gtk-scale.spec.js';
+import { GtkSpinButtonTest } from './gtk-spin-button.spec.js';
+import { GtkPasswordEntryTest } from './gtk-password-entry.spec.js';
+import { GtkSearchEntryTest } from './gtk-search-entry.spec.js';
+import { GtkLinkButtonTest } from './gtk-link-button.spec.js';
+import { GtkScaleButtonTest } from './gtk-scale-button.spec.js';
+import { GtkColorDialogButtonTest } from './gtk-color-dialog-button.spec.js';
+import { GtkFontDialogButtonTest } from './gtk-font-dialog-button.spec.js';
+import { AdwBinTest } from './adw-bin.spec.js';
+import { AdwClampScrollableTest } from './adw-clamp-scrollable.spec.js';
+import { AdwPreferencesRowTest } from './adw-preferences-row.spec.js';
+import { AdwTabBarTest } from './adw-tab-bar.spec.js';
+import { AdwTabButtonTest } from './adw-tab-button.spec.js';
+import { AdwTabOverviewTest } from './adw-tab-overview.spec.js';
+import { AdwViewSwitcherSidebarTest } from './adw-view-switcher-sidebar.spec.js';
+import { GtkEditableLabelTest } from './gtk-editable-label.spec.js';
+import { GtkSearchBarTest } from './gtk-search-bar.spec.js';
+import { GtkTextTest } from './gtk-text.spec.js';
+import { GtkTextViewTest } from './gtk-text-view.spec.js';
+import { GtkFrameTest } from './gtk-frame.spec.js';
+import { GtkAspectFrameTest } from './gtk-aspect-frame.spec.js';
+import { GtkCenterBoxTest } from './gtk-center-box.spec.js';
+import { GtkGridTest } from './gtk-grid.spec.js';
+import { GtkFixedTest } from './gtk-fixed.spec.js';
+import { GtkScrolledWindowTest } from './gtk-scrolled-window.spec.js';
+import { GtkScrollbarTest } from './gtk-scrollbar.spec.js';
+import { GtkViewportTest } from './gtk-viewport.spec.js';
+import { GtkWindowHandleTest } from './gtk-window-handle.spec.js';
 import { GtkBoxTest } from './gtk-box.spec.js';
 import { GtkLabelTest } from './gtk-label.spec.js';
+// The media group, after `GtkLabelTest` because `<gtk-media-controls>` adopts its stream from
+// the nearest ancestor `<gtk-video>` and `<gtk-inscription>` asserts the `.numeric`-shaped
+// label rules `GtkLabelTest` established — neither is order-dependent, but grouping the four
+// here is what makes the block findable.
+import { GtkPictureTest } from './gtk-picture.spec.js';
+import { GtkInscriptionTest } from './gtk-inscription.spec.js';
+import { GtkVideoTest } from './gtk-video.spec.js';
+import { GtkMediaControlsTest } from './gtk-media-controls.spec.js';
 import { AdwAboutDialogTest } from './adw-about-dialog.spec.js';
 import { AdwStyleClassesTest } from './style-classes.spec.js';
 import { AdwAccentTest } from './adw-accent.spec.js';
@@ -58,6 +135,7 @@ import { AdwEmptySectionsTest } from './empty-sections.spec.js';
 import { AdwSlottedChildrenTest } from './slotted-children.spec.js';
 import { AdwKeyboardOperableTest } from './keyboard-operable.spec.js';
 import { AdwFontsTest } from './adw-fonts.spec.js';
+import { AdwConstructVectorsTest } from './construct-vectors.spec.js';
 import { AdwSharedTreesTest } from './shared-trees.spec.js';
 import { AdwBlueprintTreeTest } from './blueprint-tree.spec.js';
 import { AdwValueListsTest } from './value-lists.spec.js';
@@ -68,6 +146,7 @@ import { AdwFontStackTest } from './font-stack.spec.js';
 
 run({
     AdwSharedTreesTest,
+    AdwConstructVectorsTest,
     AdwBlueprintTreeTest,
     AdwValueListsTest,
     AdwBlueprintLayoutTest,
@@ -90,8 +169,68 @@ run({
     GtkSwitchTest,
     AdwChecksTest,
     GtkProgressBarTest,
+    GtkLevelBarTest,
+    GtkSpinnerTest,
+    GtkStackTest,
+    GtkStackSwitcherTest,
+    GtkStackSidebarTest,
+    GtkNotebookTest,
+    GtkColumnViewTest,
+    GtkGridViewTest,
+    GtkListViewTest,
+    GtkHeaderBarTest,
+    GtkWindowControlsTest,
+    GtkWindowTest,
+    GtkApplicationWindowTest,
+    GtkActionBarTest,
+    GtkSeparatorTest,
+    GtkCalendarTest,
+    GtkFlowBoxTest,
+    GtkListBoxTest,
+    GtkTreeExpanderTest,
+    GtkDrawingAreaTest,
+    GtkDragIconTest,
+    GtkGLAreaTest,
+    GtkGraphicsOffloadTest,
+    GtkToggleButtonTest,
+    GtkExpanderTest,
+    GtkOverlayTest,
+    GtkPanedTest,
+    GtkRevealerTest,
+    GtkScaleTest,
+    GtkSpinButtonTest,
+    GtkPasswordEntryTest,
+    GtkSearchEntryTest,
+    GtkLinkButtonTest,
+    GtkScaleButtonTest,
+    GtkColorDialogButtonTest,
+    GtkFontDialogButtonTest,
+    AdwBinTest,
+    AdwClampScrollableTest,
+    AdwPreferencesRowTest,
+    AdwTabBarTest,
+    AdwTabButtonTest,
+    AdwTabOverviewTest,
+    AdwViewSwitcherSidebarTest,
+    GtkEditableLabelTest,
+    GtkTextTest,
+    GtkTextViewTest,
+    GtkSearchBarTest,
+    GtkFrameTest,
+    GtkAspectFrameTest,
+    GtkCenterBoxTest,
+    GtkGridTest,
+    GtkFixedTest,
+    GtkScrolledWindowTest,
+    GtkScrollbarTest,
+    GtkViewportTest,
+    GtkWindowHandleTest,
     GtkBoxTest,
     GtkLabelTest,
+    GtkPictureTest,
+    GtkInscriptionTest,
+    GtkVideoTest,
+    GtkMediaControlsTest,
     AdwAvatarTest,
     AdwCarouselTest,
     AdwBottomSheetTest,
@@ -104,8 +243,13 @@ run({
     AdwButtonRowTest,
     AdwActionRowsTest,
     AdwBreakpointsTest,
+    AdwBreakpointBinTest,
+    AdwMultiLayoutViewTest,
     AdwDataGridTest,
     AdwDialogTest,
+    AdwWindowTest,
+    AdwShortcutsTest,
+    AdwApplicationWindowTest,
     GtkDropDownTest,
     AdwRowStateTest,
     AdwTabViewTest,
@@ -116,9 +260,17 @@ run({
     AdwHeaderBarTest,
     GtkEntryTest,
     GtkMenuButtonTest,
+    GtkPopoverTest,
+    GtkPopoverRoleTest,
+    GtkPopoverBinTest,
+    GtkPopoverMenuTest,
+    GtkPopoverMenuBarTest,
     GioMenuTest,
     GtkValueDoorsTest,
     GtkButtonTest,
+    GtkAboutDialogTest,
+    GtkEmojiChooserTest,
+    GtkPrintDialogsTest,
     AdwViewStackTest,
     AdwNavigationViewTest,
     AdwSidebarTest,