[WC-3505]: Gallery pagination design properties are not applied

[yordan-st]

Pull request type

Bug fix (non-breaking change which fixes an issue)

---

Description

Gallery's Pagination design property (Left / Center) has done nothing since the pagination overhaul. Its CSS keyed off a .widget-gallery-pagination wrapper that the overhaul deleted, so pagination was always right-aligned regardless of the setting.

Restoring it is not a CSS change. Pagination now lives in a three-zone flex bar (*-start / *-middle / *-end) where the zone, not the bar, decides position, and those zones are already used by the selection counter and the load more button. Overriding justify-content inside the end zone would centre pagination at ~83% of the bar width, and doing it with CSS order or grid placement would reorder visually while leaving DOM order fixed — a WCAG 2.4.3 (Focus Order) and 1.3.2 (Meaningful Sequence) defect for a paging control.

So placement is decided in markup by a pure function, resolveZones:

alignment	pagination zone	displaced to end zone	untouched
Left	*-start	selection counter	load more stays in *-middle
Center	*-middle	load more button	counter stays in *-start
Right	*-end	nothing	everything

The rule is total: at most three occupants, three zones, and custom pagination replaces the built-in bar rather than adding to it, so at most one occupant is ever displaced. Displacement was chosen over wrapping to a second row because the counter appears dynamically at selected > 0 — wrapping would shift the page the moment a user selects their first item.

The same result drives the footer, the top bar and the editor preview, so they cannot drift apart. That drift is what produced the second and third fixes below.

Also fixed here

• Custom pagination ignored Position of pagination at runtime — it always rendered below the gallery. Above grid now renders it in the top bar. Both renders it once in the footer, because a widgets placeholder rendered twice would duplicate widget instances, DOM ids and state; check() now surfaces a warning explaining that.
• The editor preview disagreed with runtime on that same setting, showing custom pagination above the gallery while the app rendered it below.

Design property changes (data-widgets)

• Pagination is now a toggle button group with Atlas align icons, matching every other alignment control in Studio Pro, and gains an explicit Right option.
• Property and option names are deliberately unchanged. Studio Pro stores design property selections by property and option name, not by CSS class, so renaming raises CE6083 and CE6087 in every existing app until a developer runs "Update all renamed design properties in project". Verified in Studio Pro during development.
• Dead .widget-gallery-pagination rules removed; fc-middle / tb-middle are now real flex zones so Center is centred by construction rather than incidentally.

Accessibility note, intended: DOM order stays start → middle → end, so alignment now also determines tab and reading order — Left puts the paging controls before the Clear selection button. Visual and focus order stay in agreement, which the CSS-only alternatives could not achieve.

Not in this PR: DataGrid 2's -padding-top container-query typo and its identical custom-pagination position bug ship separately so Gallery and DataGrid 2 changes stay reviewable apart. [WC-3547 Data Grid 2: Stack top bar in narrow containers](#2389 (comment))

Tests: 145 unit tests pass (was 131). resolveZones is covered by an exhaustive 24-combination invariant pass; the bar components are asserted against real rendered DOM per zone.

Planning artifacts: packages/pluggableWidgets/gallery-web/openspec/changes/fix-gallery-pagination-placement/.

What should be covered while testing?

Build both packages into a test project:

• packages/pluggableWidgets/gallery-web
• packages/modules/data-widgets

1. Alignment × position. Gallery with Pagination = Paging buttons. For each of Left / Center / Right, check Position of pagination = Below grid, Above grid, Both. Pagination should sit hard left, truly centred on the bar, or hard right, in both bars.
2. Displacement. Enable multi selection with Show selection count = Bottom. Select an item. With Left, pagination takes the left slot and the count moves right; with Center, the count stays left. Repeat with Show selection count = Top against the top bar.
3. No layout shift. Selecting the first item must not change the footer height or add a row.
4. All three occupants. Pagination = Load more, Show total count on, selection active. Center should give: count left, paging status centred, Load more right.
5. Custom pagination. Enable it and check Above grid (renders in the top bar), Below grid (footer), Both (footer only, plus a warning on the widget in Studio Pro). Confirm alignment moves the custom widgets too.
6. Narrow width. Shrink the gallery container below 500px — the bar should still stack vertically and centre everything, whatever the alignment.
7. Design mode. The page editor should place everything where the running app does, including custom pagination.
8. Keyboard. Tab through both bars for each alignment; focus order must follow visual order.
9. Upgrade safety. An existing page that already had Left or Center selected must show no errors and keep its selection.

[iobuhov]

One of the biggest changes I need is to replace word "zone" with "slot". Slot is more known term in frontend to denote areas where you can put your elements.
Please rewrite spec, comments, variables and other identifiers. Word "zone" is bit too alien.

[github-actions]

AI Code Review

🔶 Changes requested — one or more medium-severity items must be addressed

---

What was reviewed

File	Change
packages/pluggableWidgets/gallery-web/src/helpers/pagingAlignment.ts	New helper: parses pagination alignment from design-property class
packages/pluggableWidgets/gallery-web/src/helpers/resolveSlots.ts	New helper: pure function assigning elements to bar slots
packages/pluggableWidgets/gallery-web/src/view-models/GalleryRoot.viewModel.ts	Added pagingAlignment computed that reads from props.class
packages/pluggableWidgets/gallery-web/src/components/GalleryFooterControls.tsx	Refactored to use resolveSlots; custom pagination honours position
packages/pluggableWidgets/gallery-web/src/components/GalleryTopBarControls.tsx	Refactored to use resolveSlots; added tb-middle slot
packages/pluggableWidgets/gallery-web/src/Gallery.editorConfig.ts	Added check() for Both + custom pagination combination
packages/pluggableWidgets/gallery-web/src/Gallery.editorPreview.tsx	Aligned with runtime: uses resolveSlots, custom pagination honours position
packages/pluggableWidgets/gallery-web/src/components/__tests__/GalleryBarControls.spec.tsx	Integration tests for slot placement and custom pagination position
packages/pluggableWidgets/gallery-web/src/helpers/__tests__/pagingAlignment.spec.ts	Unit tests for class parser, including edge cases
packages/pluggableWidgets/gallery-web/src/helpers/__tests__/resolveSlots.spec.ts	Exhaustive 24-combination invariant suite
packages/pluggableWidgets/gallery-web/src/view-models/__tests__/GalleryRoot.viewModel.spec.tsx	Tests for pagingAlignment computed
packages/pluggableWidgets/gallery-web/CHANGELOG.md	Unreleased entries for alignment fix and custom pagination position fix
packages/modules/data-widgets/CHANGELOG.md	Unreleased entries mirroring gallery-web changes
packages/modules/data-widgets/src/themesource/datawidgets/web/design-properties.json	Pagination becomes ToggleButtonGroup with icons; adds Right option
packages/modules/data-widgets/src/themesource/datawidgets/web/_gallery-design-properties.scss	Removes dead CSS; adds stub rules for the three alignment classes
packages/modules/data-widgets/src/themesource/datawidgets/web/_gallery.scss	Adds explicit fc-middle/tb-middle slot rules; updates container queries
packages/pluggableWidgets/gallery-web/openspec/changes/fix-gallery-pagination-placement/	Planning artifacts: proposal, design, specs, tasks

CI: code quality check ✅, sigridci ✅, E2E (1) ✅, Snyk ✅ — release build and E2E (0) still in progress at review time.

Skipped (out of scope): dist/, pnpm-lock.yaml, openspec planning docs

---

Findings

🔶 Medium — check() reports an error instead of a warning for Both + custom pagination

File: packages/pluggableWidgets/gallery-web/src/Gallery.editorConfig.ts line 87–95
Problem: The PR description and the spec (gallery-custom-pagination-position/spec.md) both specify that Studio Pro should surface a warning for the unsupported Both + custom pagination combination:

"Studio Pro SHALL surface this limitation at design time as a warning on the widget"

The implementation pushes a Problem with severity: "error", which blocks deployment in Studio Pro — even though the widget renders correctly (custom pagination appears once in the footer). Treating a graceful degradation as a blocking error is incorrect and will surprise users who configure this combination.

Fix:

// editorConfig.ts line 88 — change severity from "error" to "warning"
errors.push({
    severity: "warning",      // was "error" — widget still renders, graceful degradation only
    property: "pagingPosition",
    message:
        "Custom pagination cannot be shown in both positions and will render below the gallery. " +
        'Set "Position of pagination" to "Above grid" or "Below grid" to choose a single position.'
});

---

⚠️ Low — it.each test description has className and slot interpolated in the wrong order

File: packages/pluggableWidgets/gallery-web/src/components/__tests__/GalleryBarControls.spec.tsx line 54–63
Note: The template string "renders pagination in the %s slot of the footer for class %s" receives [className, slot], so the output reads "renders pagination in the widget-gallery-pagination-left slot of the footer for class start" — which is backwards. The assertion itself is correct; only the generated test name is misleading in failure output.

// Swap the format tokens to match parameter order [className, slot]:
it.each([...])(
    "renders pagination in the %s slot of the footer when class is %s", // slot first, then className
    (className, slot) => { ... }
);
// Or reorder the tuple to [slot, className] and keep the original template.

---

Positives

• Exhaustive invariant suite in resolveSlots.spec.ts — the 24-combination it.each guarantees no element is assigned twice and every visible element appears exactly once, covering every alignment × element combination without hand-writing 24 separate cases.
• Pure resolveSlots function shared across footer, top bar, and editor preview — the three consumers cannot drift apart, which was precisely the root cause of the custom pagination position bug. Centralising the placement rule in a testable pure function is the right architectural call here.
• parsePagingAlignment edge-case coverage — tests verify prefix-guard (prefixed-widget-gallery-pagination-left → right), irregular whitespace, multiple alignment classes (deterministic first-match), and the undefined/empty-string fallback. These are the exact failure modes for a class-string parser.
• Design property name and option name freeze, with explicit rationale — the decision not to rename Pagination → Pagination alignment to avoid Studio Pro CE6083/CE6087 errors in every existing app is correctly documented and implemented. The Right option is added additively; no oldNames entry is needed.
• Accessibility rationale documented in both code and spec — the choice of TSX placement over CSS order/grid to keep focus order matching visual order (WCAG 2.4.3, 1.3.2) is explicit and verifiable, not just asserted.
• CHANGELOG entries in both packages are well-written user-facing prose — they explain the visible fix without leaking implementation details.