@gjsify/adwaita-core 0.31.0 → 0.33.0

package/lib/types/conformance/carousel.d.ts

@@ -0,0 +1,298 @@
+import type { CarouselDirection, CarouselOrientation, CarouselScrollSource } from '../carousel.js';
+/** One `carouselSnapPoints` expectation. */
+export interface CarouselSnapPointVector {
+    /** Per-page reveal sizes: 0 while a page animates in, 1 once settled. */
+    sizes: readonly number[];
+    /** `snapPoint[i] = (Σ_{j≤i} size[j]) − 1`. */
+    snapPoints: readonly number[];
+    /** Why this row exists. */
+    rule: string;
+}
+/** `adw_carousel_size_allocate`'s accumulation (adw-carousel.c:777-789).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CAROUSEL_PAGE_LIST_VECTORS)
+ */
+export declare const CAROUSEL_SNAP_POINT_VECTORS: ReadonlyArray<CarouselSnapPointVector>;
+/** One `carouselSizesFromSnapPoints` expectation. */
+export interface CarouselSizesFromSnapPointsVector {
+    /** Snap points as `AdwSwipeable` hands them to an indicator. */
+    snapPoints: readonly number[];
+    /** `sizes[0] = points[0] + 1`, `sizes[i] = points[i] − points[i−1]`. */
+    sizes: readonly number[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The inverse both indicators reconstruct sizes with
+ * (adw-carousel-indicator-dots.c:189-191, :248-250) — the only channel through
+ * which an indicator can learn per-page reveal state.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CAROUSEL_PAGE_LIST_VECTORS)
+ */
+export declare const CAROUSEL_SIZES_FROM_SNAP_POINTS_VECTORS: ReadonlyArray<CarouselSizesFromSnapPointsVector>;
+/** One `carouselRange` expectation. */
+export interface CarouselRangeVector {
+    /** The snap points the range is derived from. */
+    snapPoints: readonly number[];
+    /** Pending `position_shift`, which C folds into the bound (:219). */
+    positionShift: number;
+    /** Always 0. */
+    lower: number;
+    /** `MAX (0, positionShift + last snap point)`. */
+    upper: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `get_range` (adw-carousel.c:207-220).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CAROUSEL_PAGE_LIST_VECTORS)
+ */
+export declare const CAROUSEL_RANGE_VECTORS: ReadonlyArray<CarouselRangeVector>;
+/** One `carouselClampPosition` expectation. */
+export interface CarouselClampVector {
+    /** The proposed position. */
+    position: number;
+    /** The snap points defining the range. */
+    snapPoints: readonly number[];
+    /** `CLAMP (position, lower, upper)`. */
+    clamped: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `set_position`'s guard (adw-carousel.c:269).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CAROUSEL_PAGE_LIST_VECTORS)
+ */
+export declare const CAROUSEL_CLAMP_VECTORS: ReadonlyArray<CarouselClampVector>;
+/** One `carouselPageAtPosition` expectation. */
+export interface CarouselPageAtPositionVector {
+    /** The scroll position to resolve. */
+    position: number;
+    /** The snap points of the pages that count. */
+    snapPoints: readonly number[];
+    /** The page index, `-1` when there are no pages. */
+    page: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `get_page_at_position` → `get_closest_child_at` (adw-carousel.c:222-239,
+ * :180-205). The `.5` rows are the regression pins: C's comparison is a strict
+ * `>`, so an equidistant LATER page never replaces the earlier one, while both
+ * ports used `Math.round`, which rounds .5 up.
+ */
+export declare const CAROUSEL_PAGE_AT_POSITION_VECTORS: ReadonlyArray<CarouselPageAtPositionVector>;
+/** One `carouselNavigateTarget` expectation. */
+export interface CarouselNavigateVector {
+    /** Current scroll position. */
+    position: number;
+    /** Number of pages. */
+    nPages: number;
+    /** Which way the key moves. */
+    direction: CarouselDirection;
+    /** The target page, `null` when C returns FALSE. */
+    target: number | null;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `navigate_to_direction` (adw-carousel.c:475-508).
+ *
+ * The rounding here is C's `round()` — half AWAY FROM ZERO — and it is
+ * deliberately not the half-down tie-break of
+ * {@link CAROUSEL_PAGE_AT_POSITION_VECTORS}: at position 0.5 the carousel shows
+ * page 0 but an arrow key steps from page 1. libadwaita is internally
+ * inconsistent there and that is ground truth, not a defect to iron out.
+ */
+export declare const CAROUSEL_NAVIGATE_VECTORS: ReadonlyArray<CarouselNavigateVector>;
+/** One `carouselWheelStep` expectation. */
+export interface CarouselWheelVector {
+    /** Horizontal delta. */
+    deltaX: number;
+    /** Vertical delta. */
+    deltaY: number;
+    /** The carousel's orientation. */
+    orientation: CarouselOrientation;
+    /** The `GdkInputSource` class of the event. */
+    source: CarouselScrollSource;
+    /** Pages to step; `0` means the event propagates. */
+    step: -1 | 0 | 1;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `scroll_cb`'s axis/source rules (adw-carousel.c:537-559).  *
+ * CORE-ONLY: GAP — the browser carousel handles `wheel` without routing it through `resolveCarouselWheel`, and the NativeScript one has no wheel at all. Tracked in #1072
+ */
+export declare const CAROUSEL_WHEEL_VECTORS: ReadonlyArray<CarouselWheelVector>;
+/** One step of a wheel-lockout script. */
+export interface CarouselWheelLockoutStep {
+    /** The value the injected `now()` returns for this event, in ms. */
+    at: number;
+    /** Vertical delta of the event (all lockout rows use a mouse wheel). */
+    deltaY: number;
+    /** What `handleWheel` must return. */
+    step: -1 | 0 | 1;
+    /** The position afterwards. */
+    position: number;
+}
+/** One end-to-end wheel-lockout expectation. */
+export interface CarouselWheelLockoutVector {
+    /** How many settled pages the carousel starts with. */
+    pages: number;
+    /** The events, in order, each with the clock reading it arrives at. */
+    steps: readonly CarouselWheelLockoutStep[];
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `SCROLL_TIMEOUT_DURATION` (adw-carousel.c:22) and the `scroll_timeout_id` gate
+ * (:526, :571-574) — a wheel notch arms a 150 ms lockout during which further
+ * notches propagate instead of paging.
+ *
+ * The web port replaced this with a non-decaying delta accumulator, so +30 then
+ * −30 cancelled out where libadwaita pages twice, and a slow wheel never
+ * reached the threshold at all.
+ *
+ * CORE-ONLY: GAP — the lockout is a real elapsed-time rule and neither element has a clock seam to drive it with. Tracked in #1072
+ */
+export declare const CAROUSEL_WHEEL_LOCKOUT_VECTORS: ReadonlyArray<CarouselWheelLockoutVector>;
+/** One `carouselReorderShift` expectation. */
+export interface CarouselReorderShiftVector {
+    /** Snap point of the page the carousel is closest to. */
+    closestPoint: number;
+    /** Snap point the moved page had. */
+    oldPoint: number;
+    /** Snap point it lands on. */
+    newPoint: number;
+    /** The moved page's reveal size. */
+    size: number;
+    /** How far `position` must move so the visible page does not jump. */
+    shift: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** The three branches of `adw_carousel_reorder`'s compensation (adw-carousel.c:1488-1495).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CAROUSEL_PAGE_LIST_VECTORS)
+ */
+export declare const CAROUSEL_REORDER_SHIFT_VECTORS: ReadonlyArray<CarouselReorderShiftVector>;
+/**
+ * One operation in a page-list script.
+ *
+ * `insert` and `remove` mean "and finish the reveal immediately", which is what
+ * a carousel with the default `reveal-duration` of 0 (adw-carousel.c:1206) does
+ * and what both renderers' page APIs do. The mid-animation states are pinned
+ * separately by {@link CAROUSEL_REVEAL_VECTORS}.
+ */
+export type CarouselPageOp = {
+    readonly kind: 'insert';
+    readonly id: string;
+    readonly position?: number;
+} | {
+    readonly kind: 'remove';
+    readonly id: string;
+} | {
+    readonly kind: 'reorder';
+    readonly id: string;
+    readonly position: number;
+} | {
+    readonly kind: 'scrollTo';
+    readonly index: number;
+} | {
+    readonly kind: 'setPosition';
+    readonly position: number;
+} | {
+    readonly kind: 'settle';
+};
+/** The observable state a script must land in. */
+export interface CarouselStateSnapshot {
+    /** Page ids in order, excluding any whose removal is still animating. */
+    ids: readonly string[];
+    /** `adw_carousel_get_n_pages` — the same exclusion. */
+    nPages: number;
+    /** Reveal sizes of every TRACKED child, including ones being removed. */
+    sizes: readonly number[];
+    /** Snap points of every tracked child. */
+    snapPoints: readonly number[];
+    /** The clamped fractional position. */
+    position: number;
+    /** The current page index, `-1` when empty. */
+    page: number;
+}
+/** One end-to-end page-list expectation. */
+export interface CarouselPageListVector {
+    /** Pages the carousel starts with, all settled at size 1. */
+    pages: readonly string[];
+    /** The script, applied in order. */
+    ops: readonly CarouselPageOp[];
+    /** What each op returned (`settle` reports `true`). */
+    opResults: readonly boolean[];
+    /** The `page-changed` indices emitted while the script ran, in order. */
+    pageChanged: readonly number[];
+    /** The state afterwards. */
+    expected: CarouselStateSnapshot;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * Insert / remove / reorder ordering and the position compensation, on a
+ * carousel whose reveals complete instantly — the shape both renderers expose.
+ *
+ * The whole family is new to both ports: the web port snapshotted its children
+ * once in `connectedCallback` and never looked again, and the NS port had
+ * `addPage` and nothing else.
+ */
+export declare const CAROUSEL_PAGE_LIST_VECTORS: ReadonlyArray<CarouselPageListVector>;
+/** One operation in a reveal script — the mid-animation half of the state machine. */
+export type CarouselRevealOp = {
+    readonly kind: 'insert';
+    readonly id: string;
+    readonly position?: number;
+} | {
+    readonly kind: 'reveal';
+    readonly id: string;
+} | {
+    readonly kind: 'size';
+    readonly id: string;
+    readonly size: number;
+} | {
+    readonly kind: 'remove';
+    readonly id: string;
+} | {
+    readonly kind: 'setPosition';
+    readonly position: number;
+};
+/** One end-to-end reveal expectation. */
+export interface CarouselRevealVector {
+    /** Pages the carousel starts with, all settled at size 1. */
+    pages: readonly string[];
+    /** The script, applied in order. */
+    ops: readonly CarouselRevealOp[];
+    /** The state afterwards. */
+    expected: CarouselStateSnapshot;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The reveal lifecycle: a page enters at size 0 and grows, leaves `n-pages`
+ * before its geometry, and drags the position along whenever it sits at or
+ * before the page on screen.
+ *
+ * Neither port has any of this — both treat the page list as fixed — so every
+ * row is new behaviour rather than a regression pin.
+ */
+export declare const CAROUSEL_REVEAL_VECTORS: ReadonlyArray<CarouselRevealVector>;
+/** One property-default expectation. */
+export interface CarouselPropertyDefaultVector {
+    /** The `CarouselState` accessor. */
+    property: 'orientation' | 'interactive' | 'allowScrollWheel' | 'allowLongSwipes' | 'spacing' | 'revealDuration';
+    /** What a freshly constructed carousel reports. */
+    value: string | number | boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * The `AdwCarousel` property defaults. Two of them are regression pins:
+ * `allow-scroll-wheel` is TRUE, which the web port inverted by reading a bare
+ * attribute presence (so a plain `<adw-carousel>` ignored the wheel entirely
+ * while its own header comment claimed the opposite), and `allow-long-swipes` is
+ * FALSE, which the web port carried as a property whose two ternary branches
+ * were identical.
+ */
+export declare const CAROUSEL_PROPERTY_DEFAULT_VECTORS: ReadonlyArray<CarouselPropertyDefaultVector>;

package/lib/types/conformance/checks.d.ts

@@ -0,0 +1,29 @@
+import type { RadioGroupChange } from '../checks.js';
+/**
+ * One mutation in a radio scenario. DATA, not a closure: the browser suite
+ * replays these as clicks on real elements rather than as method calls.
+ */
+export interface RadioGroupStep {
+    op: 'select';
+    /** The group name — what `name` scopes in HTML, and what the state keys on. */
+    name: string;
+    /** The member's value. */
+    value: string;
+}
+/** One radio-group scenario. */
+export interface RadioGroupVector {
+    /** Short scenario name. */
+    name: string;
+    /** The members that exist, as `[group, value]` pairs — what the renderer mounts. */
+    members: ReadonlyArray<readonly [string, string]>;
+    /** The mutations, applied in order to a fresh state. */
+    steps: readonly RadioGroupStep[];
+    /** `selected(group)` afterwards, one entry per group in {@link members}. */
+    selected: ReadonlyArray<readonly [string, string | null]>;
+    /** Every change the state emits, in order. This IS the renderer's repaint feed. */
+    emitted: ReadonlyArray<RadioGroupChange>;
+    /** Why this row exists — the rule or edge case it pins down. */
+    rule: string;
+}
+/** `RadioGroupState.select` and the exclusivity it publishes. */
+export declare const RADIO_GROUP_VECTORS: ReadonlyArray<RadioGroupVector>;

package/lib/types/conformance/chrome.d.ts

@@ -0,0 +1,207 @@
+import type { AdwClampSizeClass, ClampParams, ToolbarViewAllocateInput, ToolbarViewClassInput, ToolbarViewContentForSizeInput, ToolbarViewMeasureInput } from '../chrome.js';
+/** One `clampThresholds` expectation. */
+export interface ClampThresholdsVector {
+    /** The clamp properties plus the child's measured min/nat. */
+    params: ClampParams;
+    /** `MAX (MIN (tightening_threshold, maximum_size), min)`. */
+    lower: number;
+    /** `MAX (lower, maximum_size)`. */
+    max: number;
+    /** `lower + 3 * (max - lower)`. */
+    upper: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `lower`/`max`/`upper` (adw-clamp-layout.c:173-176, :210-213).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CLAMP_ALLOCATE_VECTORS)
+ */
+export declare const CLAMP_THRESHOLD_VECTORS: ReadonlyArray<ClampThresholdsVector>;
+/** One `clampChildSize` expectation. */
+export interface ClampChildSizeVector {
+    /** The available size (`for_size`); `-1` is GTK's "unconstrained". */
+    forSize: number;
+    /** The clamp properties plus the child's measured min/nat. */
+    params: ClampParams;
+    /** What the child is allocated. */
+    childSize: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `child_size_from_clamp` (adw-clamp-layout.c:193-232).  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CLAMP_ALLOCATE_VECTORS)
+ */
+export declare const CLAMP_CHILD_SIZE_VECTORS: ReadonlyArray<ClampChildSizeVector>;
+/** One `clampSizeFromChild` expectation. */
+export interface ClampSizeFromChildVector {
+    /** The child's size. */
+    childSize: number;
+    /** The clamp properties plus the child's measured min/nat. */
+    params: ClampParams;
+    /** The size the clamp itself reports for it. */
+    clampSize: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `clamp_size_from_child` (adw-clamp-layout.c:156-191) — the inverse ease.  *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (CLAMP_ALLOCATE_VECTORS)
+ */
+export declare const CLAMP_SIZE_FROM_CHILD_VECTORS: ReadonlyArray<ClampSizeFromChildVector>;
+/** One `clampAllocate` expectation. */
+export interface ClampAllocateVector {
+    /** The size the clamp itself was allocated. */
+    availableSize: number;
+    /** The clamp properties plus the child's measured min/nat. */
+    params: ClampParams;
+    /** The size the child is allocated. */
+    childSize: number;
+    /** `ceil(max)`. */
+    childMaximum: number;
+    /** `ceil(lower)`. */
+    lowerThreshold: number;
+    /** The style class the CHILD carries. */
+    sizeClass: AdwClampSizeClass;
+    /** The centring offset. */
+    offset: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `adw_clamp_layout_allocate` (adw-clamp-layout.c:317-386). */
+export declare const CLAMP_ALLOCATE_VECTORS: ReadonlyArray<ClampAllocateVector>;
+/** One `normalizeClampSize` expectation. */
+export interface ClampPropertyVector {
+    /** The raw attribute value or property assignment. */
+    value: number | string | null | undefined;
+    /** The default the property falls back to. */
+    fallback: number;
+    /** The value that reaches the layout. */
+    size: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `maximum-size` / `tightening-threshold` as `g_param_spec_int (…, 0, G_MAXINT, …)`
+ * (adw-clamp-layout.c:413-416, :448-451).
+ *
+ * The three interesting rows are the three the ports disagreed on: `"0"` (valid,
+ * and NOT the default), a non-numeric value (never reaches the layout, so the
+ * DEFAULT applies — the browser port kept whatever cap was already set), and a
+ * negative (out of range, clamped to the range floor).
+ */
+export declare const CLAMP_PROPERTY_VECTORS: ReadonlyArray<ClampPropertyVector>;
+/** One `toolbarViewAllocate` expectation. */
+export interface ToolbarViewAllocateVector {
+    /** The measured sizes going in. */
+    input: ToolbarViewAllocateInput;
+    /** `Adw.ToolbarView:top-bar-height`. */
+    topBarHeight: number;
+    /** `Adw.ToolbarView:bottom-bar-height`. */
+    bottomBarHeight: number;
+    /** The content's allocated height. */
+    contentHeight: number;
+    /** The content's offset from the top edge. */
+    contentOffset: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `adw_toolbar_view_size_allocate` (adw-toolbar-view.c:357-406).  *
+ * CORE-ONLY: both renderers let the BROWSER and NativeScript lay the bars out rather than allocating by hand, so there is no allocation of theirs to compare — the rule they DO apply is TOOLBAR_VIEW_CLASS_VECTORS, which both drive. This reason used to live in the two `adw-toolbar-view.ts` files and nowhere a reader of this table would look
+ */
+export declare const TOOLBAR_VIEW_ALLOCATE_VECTORS: ReadonlyArray<ToolbarViewAllocateVector>;
+/** One `toolbarViewMeasure` expectation. */
+export interface ToolbarViewMeasureVector {
+    /** The measured sizes going in. */
+    input: ToolbarViewMeasureInput;
+    /** The view's minimum along the measured axis. */
+    minimum: number;
+    /** The view's natural along the measured axis. */
+    natural: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `adw_toolbar_view_measure` (adw-toolbar-view.c:266-354).  *
+ * CORE-ONLY: same as TOOLBAR_VIEW_ALLOCATE_VECTORS — neither renderer measures the bars itself
+ */
+export declare const TOOLBAR_VIEW_MEASURE_VECTORS: ReadonlyArray<ToolbarViewMeasureVector>;
+/** One `toolbarViewContentForSize` expectation. */
+export interface ToolbarViewContentForSizeVector {
+    /** The `for_size` the view was measured at. */
+    forSize: number;
+    /** The bar heights and extend flags. */
+    input: ToolbarViewContentForSizeInput;
+    /** `for_size` for the content's minimum. */
+    forSizeMin: number;
+    /** `for_size` for the content's natural. */
+    forSizeNat: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/** `adw_toolbar_view_measure`'s height-for-width branch (adw-toolbar-view.c:292-316).  *
+ * CORE-ONLY: same as TOOLBAR_VIEW_ALLOCATE_VECTORS — neither renderer measures the bars itself
+ */
+export declare const TOOLBAR_VIEW_CONTENT_FOR_SIZE_VECTORS: ReadonlyArray<ToolbarViewContentForSizeVector>;
+/** One `toolbarViewClasses` expectation. */
+export interface ToolbarViewClassVector {
+    /** The styles, extend flags and ALLOCATED bar heights. */
+    input: ToolbarViewClassInput;
+    /** Classes on the view node. */
+    view: readonly string[];
+    /** Classes on the top-bar box. */
+    topBar: readonly string[];
+    /** Classes on the bottom-bar box. */
+    bottomBar: readonly string[];
+    /** Why this row exists. */
+    rule: string;
+}
+/** `update_undershoots` (adw-toolbar-view.c:215-232) + the style setters (:1011-1024, :1097-1110). */
+export declare const TOOLBAR_VIEW_CLASS_VECTORS: ReadonlyArray<ToolbarViewClassVector>;
+/** One `spinnerGeometry` expectation. */
+export interface SpinnerGeometryVector {
+    /** Allocated box width. */
+    width: number;
+    /** Allocated box height. */
+    height: number;
+    /** `MIN (floorf (MIN (w, h) / 2), MAX_RADIUS)`. */
+    radius: number;
+    /** `2 * radius`. */
+    diameter: number;
+    /** `diameter / 8`. */
+    lineWidth: number;
+    /** `roundf (width / 2)`. */
+    centerX: number;
+    /** `roundf (height / 2)`. */
+    centerY: number;
+    /**
+     * What the browser element drew before this landed — `max(2, round(size / 12))`
+     * — or `null` for a non-square box, which that element had no notion of.
+     */
+    legacyWebLineWidth: number | null;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_spinner_paintable_snapshot_with_weight` (adw-spinner-paintable.c:342-352)
+ * + `calculate_line_width` (:314-321) at the default weight 400.
+ *
+ * `legacyWebLineWidth` stays in the table on purpose: it is the formula the
+ * browser element shipped, and it is wrong at every size above 16 — 2px where
+ * Adwaita strokes 3px at 24, 4px against 6px at 48, 5px against 8px at 64.
+ */
+export declare const SPINNER_GEOMETRY_VECTORS: ReadonlyArray<SpinnerGeometryVector>;
+/** One `resolveSpinnerSize` expectation. */
+export interface SpinnerSizeVector {
+    /** The raw attribute value or property assignment. */
+    value: number | string | null | undefined;
+    /** The box the spinner is given. */
+    size: number;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `adw_spinner_measure` (adw-spinner.c:70-84) — minimum AND natural are both
+ * `MIN_SIZE`, and GTK never allocates below a widget's minimum.
+ *
+ * The rows without a usable value all land on 16, which is the measured natural
+ * size — NOT the 24 the browser element invented nor the 32 the NativeScript
+ * widget invented.
+ */
+export declare const SPINNER_SIZE_VECTORS: ReadonlyArray<SpinnerSizeVector>;

package/lib/types/conformance/data-grid.d.ts

@@ -0,0 +1,136 @@
+import type { AdwDataGridColumn, AdwDataGridRowVariant, DataGridTrack } from '../data-grid.js';
+/** One track-derivation expectation. */
+export interface DataGridTrackVector {
+    /** What the row is about. */
+    name: string;
+    /** The column descriptors handed to `dataGridTracks`. */
+    columns: ReadonlyArray<AdwDataGridColumn>;
+    /** The renderer-neutral tracks derived from them. */
+    tracks: ReadonlyArray<DataGridTrack>;
+    /** The browser mapping — a `grid-template-columns` value. */
+    template: string;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `dataGridTracks` + `dataGridTrackTemplate`.
+ *
+ * The rule that needs the most rows is the implicit one: with NO `width` and NO
+ * `flex` anywhere, the FIRST column absorbs the slack and the rest size to
+ * content. It is global, so a single declared size anywhere in the list turns it
+ * off for every column — the pair of two-column rows below is the whole
+ * difference between "label column stretches, figures hug the right edge" and
+ * "every column hugs its content".
+ */
+export declare const DATA_GRID_TRACK_VECTORS: ReadonlyArray<DataGridTrackVector>;
+/** One cell-class expectation. */
+export interface DataGridColumnClassVector {
+    /** What the row is about. */
+    name: string;
+    /** The column descriptor. */
+    column: AdwDataGridColumn;
+    /** The effective alignment. */
+    align: string;
+    /** The full class list, in order. */
+    classes: ReadonlyArray<string>;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `dataGridColumnAlign` + `dataGridColumnClasses`.
+ *
+ * `numeric` and `mono` are libadwaita's own label classes
+ * (`_labels.scss:81-88`): `.numeric` is `font-variant-numeric: tabular-nums`,
+ * `.monospace` additionally the monospace family. They are opt-ins that stack,
+ * and `numeric` additionally moves the default alignment to the right edge —
+ * which is the entire difference between this widget and a boxed list.
+ *
+ * `align` is deliberately unvalidated (the last row): a value outside the union
+ * produces a class no stylesheet claims, and the cell keeps the base rule's
+ * alignment. The variant table below IS validated, because a bogus variant would
+ * pick an emphasis rather than merely fail to move text.
+ */
+export declare const DATA_GRID_COLUMN_CLASS_VECTORS: ReadonlyArray<DataGridColumnClassVector>;
+/** One variant-normalisation expectation. */
+export interface DataGridVariantVector {
+    /** The raw `variant` value off the row object. */
+    input: unknown;
+    /** What it normalises to. */
+    variant: AdwDataGridRowVariant;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `normalizeDataGridVariant`.
+ *
+ * Unlike the alignment, this one IS clamped: the variant picks a row's EMPHASIS
+ * — a spanning bold section title, a hairline rule above a subtotal, a double
+ * rule above the total — so an unrecognised value must fall back to the plain
+ * data row rather than to no rule at all.
+ */
+export declare const DATA_GRID_VARIANT_VECTORS: ReadonlyArray<DataGridVariantVector>;
+/** One cell-text expectation. */
+export interface DataGridCellTextVector {
+    /** The raw value under the column's key. */
+    input: string | number | boolean | undefined | null;
+    /** What the cell paints. */
+    text: string;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `dataGridCellText`.
+ *
+ * The grid formats NOTHING — a cell value is a pre-formatted string, because
+ * only the app knows the locale, the currency and the rounding. So the rule is
+ * only about the two empties, and the rows that matter are `0` and `false`: a
+ * truthiness test would blank both, and a blanked `0` in a statement column is a
+ * missing figure, not a zero one.
+ */
+export declare const DATA_GRID_CELL_TEXT_VECTORS: ReadonlyArray<DataGridCellTextVector>;
+/** One activation expectation. */
+export interface DataGridInteractiveVector {
+    /** The row's normalised variant. */
+    variant: AdwDataGridRowVariant;
+    /** The row's own `interactive` value, as it arrives (JSON can hold anything). */
+    rowFlag: unknown;
+    /** The grid-level `interactive` flag. */
+    gridInteractive: boolean;
+    /** Whether the row activates. */
+    interactive: boolean;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `dataGridRowInteractive`.
+ *
+ * Two independent rules, and both have a failure mode worth a row. Only a
+ * `normal` row can ever activate: a section header, a subtotal and a total are
+ * structure, and offering a detail view for a computed line leads nowhere. And
+ * the per-row flag overrides the grid-level one in BOTH directions, which is the
+ * part a single `||` or `&&` gets wrong.
+ */
+export declare const DATA_GRID_INTERACTIVE_VECTORS: ReadonlyArray<DataGridInteractiveVector>;
+/** One column-normalisation expectation. */
+export interface DataGridColumnNormalizeVector {
+    /** What the row is about. */
+    name: string;
+    /** The raw value — a parsed JSON attribute, so genuinely anything. */
+    input: unknown;
+    /** The normalised descriptors. */
+    columns: ReadonlyArray<AdwDataGridColumn>;
+    /** Why this row exists. */
+    rule: string;
+}
+/**
+ * `normalizeDataGridColumns`.
+ *
+ * The input is a parsed JSON attribute, so every field has to survive a value of
+ * the wrong type. Two policies run side by side and the rows say which is which:
+ * an entry WITHOUT a `key` is dropped (there is nothing to read from a row), and
+ * a field of the wrong type is coerced (`key`, `label`, `width`) or discarded
+ * (`flex`, `monospace`, `numeric`) rather than taking the whole entry down.
+ *
+ * CORE-ONLY: an internal step of a pipeline whose COMPOSED result is renderer-driven — driving it separately would assert the same thing twice (DATA_GRID_TRACK_VECTORS)
+ */
+export declare const DATA_GRID_COLUMN_NORMALIZE_VECTORS: ReadonlyArray<DataGridColumnNormalizeVector>;