@gjsify/adwaita-core 0.31.0 → 0.33.0

package/lib/types/conformance/split-button.d.ts

@@ -0,0 +1,193 @@
+import type { AdwArrowIcon, AdwMenuEntry, SplitButtonContentMode, SplitButtonDirection, SplitButtonHalfState, SplitButtonProperty, SplitButtonStyleClass } from '../split-button.js';
+/** One mutation in a {@link SplitButtonContentVector} sequence, with its outcome. */
+export interface SplitButtonContentStep {
+    /** Which slot is being set. */
+    op: 'label' | 'icon-name' | 'child';
+    /**
+     * The value passed. For `label`/`icon-name` the string itself; for `child` a
+     * KEY naming one of three distinct child objects the driver supplies, or
+     * `null` to clear the content.
+     */
+    value: string | null;
+    /** Whether the setter reports a change (and therefore notifies at all). */
+    changed: boolean;
+    /** The `notify::*` properties C emits for this one call, in emission order. */
+    notified: readonly SplitButtonProperty[];
+    /** The content mode after the step. */
+    mode: SplitButtonContentMode;
+    /** `get_label()` after the step. */
+    label: string | null;
+    /** `get_icon_name()` after the step. */
+    iconName: string | null;
+    /** The root style classes after the step. */
+    styleClasses: readonly SplitButtonStyleClass[];
+    /** Why this step exists — the rule or edge case it pins down. */
+    rule: string;
+}
+/** A scripted sequence of content mutations applied to a FRESH state. */
+export interface SplitButtonContentVector {
+    /** Which upstream test (or derivation) this sequence transcribes. */
+    name: string;
+    /** The mutations, in order. */
+    steps: readonly SplitButtonContentStep[];
+}
+/**
+ * The content machine (adw-split-button.c:661-682, :749-771, :799-824).
+ *
+ * Two things in here are easy to get wrong and are asserted explicitly. First,
+ * the `notified` ORDER: C freezes, notifies the slots it is about to CLEAR, sets
+ * the new one, notifies it, then thaws — so one `set_label()` can emit three
+ * notifications. Second, `child` is notified far more often than a reader
+ * expects, because `adw_split_button_get_child()` returns GtkButton's INTERNAL
+ * label/image widget in label/icon mode (the upstream suite states this at
+ * tests/test-split-button.c:155-157) and the C guard tests that pointer, not
+ * whether the app ever set a child.
+ *
+ * A driver that cannot express a step — a DOM element has no `child` slot —
+ * asserts the sequence up to that step and stops; every sequence is written so
+ * the interesting rows come first.
+ */
+export declare const SPLIT_BUTTON_CONTENT_VECTORS: ReadonlyArray<SplitButtonContentVector>;
+/** One `update_style_classes` expectation. */
+export interface SplitButtonStyleClassVector {
+    /** `gtk_button_get_label()`. */
+    label: string | null;
+    /** `gtk_button_get_icon_name()`. */
+    iconName: string | null;
+    /** The classes on the `splitbutton` node. */
+    classes: readonly SplitButtonStyleClass[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `update_style_classes` (adw-split-button.c:145-165). Both branches read the
+ * FIRST CHARACTER, which is why `''` and `'  '` land on opposite sides.
+ */
+export declare const SPLIT_BUTTON_STYLE_CLASS_VECTORS: ReadonlyArray<SplitButtonStyleClassVector>;
+/** One `set_dropdown_tooltip` expectation. */
+export interface SplitButtonTooltipVector {
+    /** The value passed to `adw_split_button_set_dropdown_tooltip`. */
+    tooltip: string;
+    /** What the dropdown actually shows. */
+    text: string;
+    /** Whether it is Pango MARKUP (`set_tooltip_markup`) rather than plain text. */
+    markup: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The tooltip fallback (adw-split-button.c:1044-1051, initial value :531-532).
+ *
+ * `has_dropdown_tooltip = tooltip && *tooltip`. The empty branch is the one both
+ * renderers got wrong: the browser port hardcoded `Menu` and, because `''` is not
+ * nullish, `dropdown-tooltip=""` left the button with NO accessible name at all;
+ * the NativeScript port had neither tooltip nor accessible name.
+ */
+export declare const SPLIT_BUTTON_TOOLTIP_VECTORS: ReadonlyArray<SplitButtonTooltipVector>;
+/** One direction expectation. */
+export interface SplitButtonDirectionVector {
+    /** The `GtkArrowType`. */
+    direction: SplitButtonDirection;
+    /** The symbolic icon the arrow node draws. */
+    arrowIcon: AdwArrowIcon;
+    /** Where the popup is placed. */
+    popupDirection: SplitButtonDirection;
+    /** Why this row exists — naming the selector that WINS, not the one that loses. */
+    rule: string;
+}
+/**
+ * Direction → glyph for the dropdown half of a SPLIT BUTTON, and → popup
+ * placement (adw-split-button.c:415).
+ *
+ * `none` is the row that matters, and it is the row that was WRONG here until the
+ * override was found: the four shared directions come from `menubutton arrow`
+ * (_buttons.scss:457-468), but `.none` is re-declared inside `splitbutton { … }`
+ * at :621-623, and that selector wins. See the header of `./index.ts` — "cite the
+ * winning selector" — for what this table cost.
+ */
+export declare const SPLIT_BUTTON_DIRECTION_VECTORS: ReadonlyArray<SplitButtonDirectionVector>;
+/**
+ * The same axis for a PLAIN `menubutton`, where nothing overrides `.none`.
+ *
+ * This table is not decoration: it is what makes the split button's row above a
+ * demonstrated OVERRIDE rather than an assertion. Holding both means a reader can
+ * see the two values and the two selectors side by side, and a renderer that
+ * reaches for the wrong one fails a test that names which widget it is drawing.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (SPLIT_BUTTON_DIRECTION_VECTORS)
+ */
+export declare const MENU_BUTTON_DIRECTION_VECTORS: ReadonlyArray<SplitButtonDirectionVector>;
+/** One `update_state` expectation. */
+export interface SplitButtonRootStateVector {
+    /** State flags of the action half. */
+    action: SplitButtonHalfState;
+    /** State flags of the dropdown (arrow) half. */
+    dropdown: SplitButtonHalfState;
+    /** Whether the root reads ACTIVE. */
+    active: boolean;
+    /** Whether the root reads CHECKED. */
+    checked: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `update_state` (adw-split-button.c:118-143) — an OR-fold of both halves onto
+ * the root, which is what `splitbutton.flat:active/:checked` styles
+ * (_buttons.scss:542-549).
+ *
+ * CORE-ONLY: GAP — two of its three axes are hardcoded in the renderer, so there is nothing to vary. Tracked in #1072
+ */
+export declare const SPLIT_BUTTON_ROOT_STATE_VECTORS: ReadonlyArray<SplitButtonRootStateVector>;
+/** One `parseMenuEntries` expectation. */
+export interface SplitButtonMenuParseVector {
+    /** The raw `menu` attribute (or `null` when absent). */
+    json: string | null;
+    /** The entries it yields. */
+    entries: readonly AdwMenuEntry[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * Menu-attribute parsing — the byte-identical helper both browser elements
+ * carried. Total: nothing an author can type may prevent the widget upgrading.
+ */
+export declare const SPLIT_BUTTON_MENU_PARSE_VECTORS: ReadonlyArray<SplitButtonMenuParseVector>;
+/** One activate-by-position expectation. */
+export interface SplitButtonMenuActivationVector {
+    /** The menu model. */
+    entries: readonly AdwMenuEntry[];
+    /** The position activated. */
+    index: number;
+    /** The entry that must be dispatched, or `null`. */
+    activated: AdwMenuEntry | null;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * Activation is BY POSITION, never by label lookup: a `GMenuModel` addresses its
+ * items by index and each carries its own detailed action (adw-split-button.c:385-388).
+ */
+export declare const SPLIT_BUTTON_MENU_ACTIVATION_VECTORS: ReadonlyArray<SplitButtonMenuActivationVector>;
+/**
+ * One dropdown-sensitivity expectation. A driver installs the popover FIRST (when
+ * {@link SplitButtonDropdownVector.popover} is set) and the menu model second, so
+ * a row with both also exercises the dissociation.
+ */
+export interface SplitButtonDropdownVector {
+    /** The menu model to install (empty = none). */
+    entries: readonly AdwMenuEntry[];
+    /** Whether a popover is installed before it. */
+    popover: boolean;
+    /** Whether the dropdown half is live. */
+    enabled: boolean;
+    /** Whether the menu can be popped up at all. */
+    canOpen: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * "If the menu model is `NULL`, the dropdown is disabled" (adw-split-button.c:376-378),
+ * and the same for the popover (:394-396). An empty entry list is the renderers'
+ * only spelling of "no menu", so it collapses onto the `NULL` case.
+ */
+export declare const SPLIT_BUTTON_DROPDOWN_VECTORS: ReadonlyArray<SplitButtonDropdownVector>;

package/lib/types/conformance/split-view.d.ts

@@ -0,0 +1,301 @@
+import type { AdwLengthUnit } from '../length-unit.js';
+import type { AdwPackType, AdwTextDirection, NavigationActionResult, NavigationStackPlan, OverlaySplitViewLayout, SidebarWidthSpec, SplitViewPaneRect } from '../split-view.js';
+/** One `adwLengthToPx` expectation. */
+export interface AdwLengthUnitVector {
+    unit: AdwLengthUnit;
+    value: number;
+    /** The `gtk-xft-dpi` in play. */
+    dpi: number;
+    /** The resulting pixel length. */
+    px: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `adw_length_unit_to_px` (adw-length-unit.c:72-81).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (SIDEBAR_BOUNDS_VECTORS, which both renderers drive)
+ */
+export declare const ADW_LENGTH_UNIT_VECTORS: ReadonlyArray<AdwLengthUnitVector>;
+/** One `glibClamp` expectation. */
+export interface GlibClampVector {
+    x: number;
+    low: number;
+    high: number;
+    /** What GLib's CLAMP returns. */
+    clamped: number;
+    rule: string;
+}
+/**
+ * GLib's `CLAMP` (gmacros.h) — HIGH is tested first.
+ *
+ * The inverted rows are the point: `Math.min(high, Math.max(low, x))` returns
+ * `high` there, and `allocate_uncollapsed` reaches inverted bounds whenever the
+ * content pane's own minimum leaves less room than `min-sidebar-width`.
+ *
+ * CORE-ONLY: GLib’s CLAMP itself — a primitive with no widget surface; every widget that reaches it does so through a table that IS driven
+ */
+export declare const GLIB_CLAMP_VECTORS: ReadonlyArray<GlibClampVector>;
+/** One `resolveSidebarBounds` expectation. */
+export interface SidebarBoundsVector {
+    spec: SidebarWidthSpec;
+    /** The sidebar child's own minimum width. */
+    sidebarChildMin: number;
+    /** `true` for the allocate paths (which `ceil()`), `false` for the measure paths. */
+    ceil: boolean;
+    min: number;
+    max: number;
+    rule: string;
+}
+/**
+ * The `MAX (…, adw_length_unit_to_px (…))` pair both widgets open with —
+ * allocate flavour at adw-navigation-split-view.c:292-300 /
+ * adw-overlay-split-view.c:452-460, measure flavour at :251-256 / :545-550.
+ */
+export declare const SIDEBAR_BOUNDS_VECTORS: ReadonlyArray<SidebarBoundsVector>;
+/** One allocated-sidebar-width expectation. */
+export interface SidebarWidthVector {
+    /** Which widget's rule applies — they answer the same input differently. */
+    widget: 'navigation' | 'overlay';
+    spec: SidebarWidthSpec;
+    totalWidth: number;
+    /** The content pane's own minimum width. */
+    contentMin: number;
+    /** The sidebar child's own minimum width. */
+    sidebarChildMin: number;
+    /** Overlay only: collapsed ignores the fraction and clamps the VIEW width. */
+    collapsed: boolean;
+    /** The allocated sidebar width. */
+    width: number;
+    rule: string;
+}
+/**
+ * `allocate_uncollapsed` (adw-navigation-split-view.c:292-304) versus
+ * `get_sidebar_width` + `allocate_uncollapsed` (adw-overlay-split-view.c:441-466, :585).
+ *
+ * The 300px pair is the reason this table keys on `widget`: identical input, 180 in
+ * the navigation split view and 100 in the overlay, because one caps the BOUND and
+ * the other caps the RESULT.
+ */
+export declare const SIDEBAR_WIDTH_VECTORS: ReadonlyArray<SidebarWidthVector>;
+/** One `resolveNaturalSidebarWidth` expectation. */
+export interface NaturalSidebarWidthVector {
+    contentNatural: number;
+    min: number;
+    max: number;
+    fraction: number;
+    natural: number;
+    rule: string;
+}
+/**
+ * `measure_uncollapsed`'s sidebar estimate (adw-navigation-split-view.c:260-262,
+ * adw-overlay-split-view.c:554-556) — the sidebar's OWN natural width is ignored.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (SIDEBAR_WIDTH_VECTORS)
+ */
+export declare const NATURAL_SIDEBAR_WIDTH_VECTORS: ReadonlyArray<NaturalSidebarWidthVector>;
+/** One `measureSplitViewHorizontal` expectation. */
+export interface SplitViewMeasureVector {
+    min: number;
+    max: number;
+    sidebarNatural: number;
+    contentMin: number;
+    contentNatural: number;
+    showProgress: number;
+    minimum: number;
+    natural: number;
+    rule: string;
+}
+/**
+ * `measure_uncollapsed` (adw-overlay-split-view.c:558-563; the navigation variant at
+ * adw-navigation-split-view.c:264-267 is the same rule at progress 1).
+ *
+ * This is the container minimum neither renderer had — which is why in both of them
+ * the content pane shrinks to nothing instead of the window refusing to get narrower.
+ *
+ * CORE-ONLY: the container minimum lands as `min-width: min-content` on the content pane, which is CSS’s own spelling of the same rule — there is no computed number of ours to compare. Asserted in the renderer as "the pane is not crushable" instead
+ */
+export declare const SPLIT_VIEW_MEASURE_VECTORS: ReadonlyArray<SplitViewMeasureVector>;
+/** One `layoutNavigationSplitView` expectation. */
+export interface NavigationLayoutVector {
+    totalWidth: number;
+    sidebarWidth: number;
+    sidebarPosition: AdwPackType;
+    direction: AdwTextDirection;
+    sidebar: SplitViewPaneRect;
+    content: SplitViewPaneRect;
+    rule: string;
+}
+/** `allocate_uncollapsed` (adw-navigation-split-view.c:306-316). */
+export declare const NAVIGATION_SPLIT_VIEW_LAYOUT_VECTORS: ReadonlyArray<NavigationLayoutVector>;
+/** One `layoutOverlaySplitView` expectation. */
+export interface OverlayLayoutVector {
+    totalWidth: number;
+    sidebarWidth: number;
+    showProgress: number;
+    collapsed: boolean;
+    sidebarPosition: AdwPackType;
+    direction: AdwTextDirection;
+    /** The full expected allocation, including the shield/paint/shadow state. */
+    layout: OverlaySplitViewLayout;
+    rule: string;
+}
+/**
+ * `allocate_uncollapsed` (adw-overlay-split-view.c:572-610) and `allocate_collapsed`
+ * (:653-703), plus `update_shield` (:249-256) and the snapshot gate (:757).
+ *
+ * `shadowProgress` is inverted relative to the reveal — 1 means NO shadow
+ * (adw-shadow-helper.c:234-249).
+ */
+export declare const OVERLAY_SPLIT_VIEW_LAYOUT_VECTORS: ReadonlyArray<OverlayLayoutVector>;
+/** One `tagsConflict` expectation. */
+export interface TagsConflictVector {
+    sidebarTag: string | null;
+    contentTag: string | null;
+    conflict: boolean;
+    rule: string;
+}
+/** `tags_equal` (adw-navigation-split-view.c:413-429).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (the tag guard, driven through NAVIGATION_ACTION_VECTORS and the refusal tests in both renderer suites)
+ */
+export declare const TAGS_CONFLICT_VECTORS: ReadonlyArray<TagsConflictVector>;
+/** One `resolveNavigationStack` expectation. */
+export interface NavigationStackVector {
+    hasSidebar: boolean;
+    hasContent: boolean;
+    sidebarPosition: AdwPackType;
+    showContent: boolean;
+    /** Whether the animated (`set_show_content`) branch applies. */
+    changingPage: boolean;
+    plan: NavigationStackPlan;
+    rule: string;
+}
+/**
+ * `update_navigation_stack` (adw-navigation-split-view.c:342-405).
+ *
+ * The lone-child rows are the ones both renderers fail: their CSS / `visibility`
+ * tables key on `show-content` alone, so a collapsed split view holding only a
+ * sidebar renders nothing at all.
+ */
+export declare const NAVIGATION_STACK_VECTORS: ReadonlyArray<NavigationStackVector>;
+/** One `resolveNavigationAction` expectation. */
+export interface NavigationActionVector {
+    action: 'push' | 'pop';
+    /** `push` only — the tag the action names. */
+    tag?: string;
+    sidebarTag?: string | null;
+    contentTag?: string | null;
+    /** `pop` only. */
+    hasSidebar?: boolean;
+    /** `pop` only. */
+    hasContent?: boolean;
+    showContent: boolean;
+    collapsed: boolean;
+    result: NavigationActionResult;
+    rule: string;
+}
+/**
+ * `navigation_push_cb` (adw-navigation-split-view.c:644-685) and `navigation_pop_cb`
+ * (:687-702) — documented as working even when NOT collapsed (:124-132).
+ */
+export declare const NAVIGATION_ACTION_VECTORS: ReadonlyArray<NavigationActionVector>;
+/** The observable state of an `OverlaySplitViewState`. */
+export interface OverlaySplitViewSnapshot {
+    showSidebar: boolean;
+    collapsed: boolean;
+    showProgress: number;
+    shieldVisible: boolean;
+    sidebarFocusable: boolean;
+    contentFocusable: boolean;
+}
+/** One collapse-coupling expectation. */
+export interface OverlayCollapseVector {
+    /** Constructor options. */
+    initial: {
+        collapsed?: boolean;
+        showSidebar?: boolean;
+        pinSidebar?: boolean;
+    };
+    /** State right after construction. */
+    before: OverlaySplitViewSnapshot;
+    /** The `collapsed` value to set. */
+    setCollapsed: boolean;
+    /** State after the change. */
+    after: OverlaySplitViewSnapshot;
+    /** Which `notify::*` properties fire, in order. */
+    notifications: ReadonlyArray<'show-sidebar' | 'collapsed'>;
+    rule: string;
+}
+/**
+ * `adw_overlay_split_view_init` (:1106-1116) + `set_collapsed` (:1439-1481) +
+ * the can-focus pair (:330-331).
+ *
+ * `if (!self->pin_sidebar) set_show_sidebar (self, !self->collapsed, FALSE, 0);` is
+ * the single rule BOTH storybooks re-implemented by hand because neither widget
+ * offered it. `show-sidebar` is notified before `collapsed` because GTK freezes
+ * notifications across the whole setter and thaws them in queue order.
+ */
+export declare const OVERLAY_COLLAPSE_VECTORS: ReadonlyArray<OverlayCollapseVector>;
+/** One `resolveSwipeSnapPoints` expectation. */
+export interface SwipeSnapPointVector {
+    showProgress: number;
+    enableShowGesture: boolean;
+    enableHideGesture: boolean;
+    swipeActive: boolean;
+    snapPoints: number[];
+    rule: string;
+}
+/** `adw_overlay_split_view_get_snap_points` (adw-overlay-split-view.c:1214-1243). */
+export declare const OVERLAY_SWIPE_SNAP_POINT_VECTORS: ReadonlyArray<SwipeSnapPointVector>;
+/** One `resolveSwipeStart` expectation. */
+export interface SwipeStartVector {
+    showProgress: number;
+    collapsed: boolean;
+    direction: 'forward' | 'back';
+    enableShowGesture: boolean;
+    enableHideGesture: boolean;
+    detected: boolean;
+    rule: string;
+}
+/** `prepare_cb` (adw-overlay-split-view.c:362-387). */
+export declare const OVERLAY_SWIPE_START_VECTORS: ReadonlyArray<SwipeStartVector>;
+/** One `resolveSwipeRelease` expectation. */
+export interface SwipeReleaseVector {
+    to: number;
+    showSidebar: boolean;
+    /** `animate` = settle only; `set-show-sidebar` = a real property change. */
+    kind: 'animate' | 'set-show-sidebar';
+    /** The resulting `show-sidebar`, for the `set-show-sidebar` case. */
+    showSidebarAfter: boolean;
+    rule: string;
+}
+/** `end_swipe_cb` (adw-overlay-split-view.c:414-429). */
+export declare const OVERLAY_SWIPE_RELEASE_VECTORS: ReadonlyArray<SwipeReleaseVector>;
+/** One `swipeCancelProgress` expectation. */
+export interface SwipeCancelVector {
+    showProgress: number;
+    cancelProgress: number;
+    rule: string;
+}
+/** `adw_overlay_split_view_get_cancel_progress` (adw-overlay-split-view.c:1253-1258). */
+export declare const OVERLAY_SWIPE_CANCEL_VECTORS: ReadonlyArray<SwipeCancelVector>;
+/** One `resolveSwipeArea` expectation. */
+export interface SwipeAreaVector {
+    isDrag: boolean;
+    sidebarWidth: number;
+    showProgress: number;
+    totalWidth: number;
+    totalHeight: number;
+    sidebarPosition: AdwPackType;
+    direction: AdwTextDirection;
+    area: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    rule: string;
+}
+/**
+ * `adw_overlay_split_view_get_swipe_area` (adw-overlay-split-view.c:1261-1290);
+ * `ADW_SWIPE_BORDER` is 32 (adw-swipe-tracker-private.h:17).
+ */
+export declare const OVERLAY_SWIPE_AREA_VECTORS: ReadonlyArray<SwipeAreaVector>;