LibreChat/e2e/specs/mock/scenarios/tool-library-small-screen.spec.ts
Marco Beretta 5c72d4146e
📱 fix: Fit the Tool Library and Skills Pickers to Small Screens (#16067)
* 📱 fix: Fit the Tool Library and Skills Pickers to Small Screens

The Tool Library dialog assumed a viewport wide enough for its 224px
navigation rail: below `md` the rail took more than half of a 390px
screen and the card grid was squeezed into the remainder. The rail is
now `md`-only, and the same kind and view navigation renders as a
horizontally scrollable chip row under the search field.

Card and row actions were hover-only, so Configure, Favorite and Remove
were unreachable on a touch screen. They stay hidden until hover only
where hover exists (`@media (hover: hover)`), and are always visible
otherwise.

The Skills picker header put the create button, the filter field and the
view radio on one row, where the field collapsed to 50px beside a
`shrink-0` radio. The view radio and the create button now sit on the
title row, the create button flush right, and the filter field owns the
row below them.

The dialogs fill the viewport below `md` and switch `vh` to `dvh`, so
mobile browser chrome no longer cuts off the bottom of the panel.

* ♿ fix: Gate Hidden Tool Actions on Touch, Not on Hover

Hiding an action until hover has to ask whether a finger can reach it, and
`(hover: hover)` does not answer that: on a 2-in-1 it is true because it
describes the trackpad, while the touchscreen sits right next to it. Tool cards
and tool rows gated their Configure, Favorite and Remove controls on that query,
so a finger user of such a device saw no actions at all.

`packages/client/tailwind.preset.cjs` already carries `touch` for this exact
distinction, `(any-pointer: coarse)` rather than `(pointer: coarse)`. This adds
its inverse, `no-touch`, and gates the hidden state on it, so the hide applies
only where no coarse pointer exists at all and hover no longer takes part in the
decision.

* 📐 fix: Split the Skills Header Onto Two Rows Below md

The Skills header put the create button, the filter field and the view radio on
one row. The radio's segments are `whitespace-nowrap`, so the group never
narrows below 261px, and the field — `flex-1`, basis 0 — absorbed the shortfall
and measured 50px on a 390px screen.

Below md the radio and the create button now take the first line, the create
button flush right, and the field takes the second. From md the row is exactly
what it was: create button, field, category, radio. One DOM order serves both
through `order-*`, so the radio and the create button each exist once.

* 🧷 fix: Let the Skills View Radio Wrap Instead of Clipping

The three view segments carry `whitespace-nowrap` and `px-4`, so the group has a
hard 261px minimum in English and more in longer locales. On a 360px phone that
group and the 42px create button exceed the dialog, which is `overflow-hidden`,
and the trailing option becomes unreachable. The group now uses the primitive's
`wrap` variant and may shrink, so the segments flow onto a second row; at 390px
they still occupy one.

`wrap` reproduced `inset-y-1` by assuming the group had no vertical padding, so
turning it on for a `p-1` group shrank the moving indicator by 8px and left it
floating inside its segment. It now measures that padding from the first row's
offset, which leaves an unpadded group's geometry unchanged.

* 🧪 test: Cover the Small-Screen Tool Library and Skills Header

Ten mock-harness scenarios for the behaviour this branch changes, one per
acceptance scenario id, asserting rendered geometry and computed styles rather
than class strings.

The tool library file covers a phone viewport (the dialog fills it, the rail is
gone, the chip row filters, and no card crosses the viewport edge — the 744px
grid-column overflow), the action gate on all three pointer profiles (visible
with a coarse pointer, hover-gated with a mouse, revealed by keyboard focus),
the selected tool row, and the unchanged desktop rail.

The skills file covers the two-row header below md, the wrapped view radio at
320 and 280 CSS px with every option inside the dialog and the indicator on its
checked segment, and the single desktop row.

* 🧪 test: Pin the Scenario Contexts and Settle Their Geometry

The verifier runs every tagged test in three projects, one of which is a touch
phone, so the mouse scenarios asserted a mouse on a device that reports a coarse
pointer, and the desktop rail on a 412px screen. They now pin their own viewport
and pointer instead of inheriting the project.

Geometry and opacity were also read mid-animation: the dialog scales as it
opens, which put its left edge at 1.5px rather than 0, and the actions fade over
the shared motion duration, which caught keyboard focus at 0.84. Both now poll
for the resting value.

With nothing selected the skills section offers only the dashed empty-state
card, whose accessible name carries the hint line, so the exact-name locator for
Add skill never matched.

* 📏 fix: Keep the Tool Library Shell and Its Body the Same Height

Giving the shell an explicit `md:h-[88vh]` while the body kept its 840px ceiling
let the two disagree: on a viewport taller than about 955px the difference became
dead space below the catalog, 216px at 1280x1200, and below `md` the full-height
sheet left 293px on a 744x1133 tablet.

The body carries the height from `md` again, the way it did before this change,
so the shell wraps it. Below `md` the shell stays the full-bleed sheet and the
body is capped to the same `100dvh`, which it needs because its `h-full`
resolves against a grid area sized to the whole catalog.

Measured shell and body heights now agree exactly: 840 at 1280x1200, 757 at
1280x860, 1133 at 744x1133 and 844 at 390x844, with the catalog still scrolling
inside its own container.

* 🎯 fix: Keep the Search Field Clear of the Dialog Close Button

`md:px-6` on the search row is a responsive variant, so it is emitted after the
base utilities and reset the `pr-12` that reserves room for the close button:
on desktop the row's right padding dropped from 48px to 24px and the field ran
16px underneath the button. It now sets only the left side at `md`.

Measured gap between the field's right edge and the button: 8px at 1280x860 and
at 390x844, with no vertical overlap. Asserted inside the phone-viewport and
desktop-rail scenarios rather than as a new id, since it is the same surface.

* ⌨️ fix: Read the Skills Header in Tab Order and Keep the Chip Row Draggable

Two defects with the same shape: a control that the eye can reach and the
keyboard or the mouse cannot.

The Skills header used `order-*` to serve both layouts from one DOM order, which
left tab order disagreeing with the visual order from `md`: focus went from the
rightmost radio group back to the create button and then into the middle. The
breakpoint now selects the DOM order instead, the way the marketplace dialog
already selects its rail, so each layout reads in the order it renders. Every
control is still built once, so there is one radio group and one create button at
any width.

The mobile chip row hid its scrollbar unconditionally. A narrow desktop window is
below `md` as well, and there a wheel scrolls the page rather than the row, so
Made by you and Favorites could not be reached with a mouse at all. The hiding is
now gated on `touch`, the same `(any-pointer: coarse)` query the rest of this
branch uses.

Measured: desktop DOM order create, field, radio and mobile radio, create, field,
each matching its layout; `scrollbar-width` resolves to `auto` in a 520px mouse
window whose row overflows, and to `none` on a touch phone.

* 👆 fix: Give the Touch Layout Touch Geometry

Two findings with one cause: the coarse-pointer layout inherited the mouse
layout's geometry after this branch changed what it shows and in what order.

Card actions no longer fade out where a finger can reach them, but they are
absolutely positioned over the card's content, so on touch they covered the last
line of a three-line description for as long as the card was on screen - an
overlap that used to be transient. The card now reserves a strip for them there,
`touch:h-36` with `touch:pb-9` on the content, which keeps all three lines.

The chip row is that layout's primary navigation and exists only where a finger
is what reaches it, yet its chips were about 30px tall and its create control
32px, while the repository already exposes the 44px `theme-control-touch` size
for this. Both now carry that floor through `touch:`, and the mouse layout keeps
its compact sizing.

Measured on a 390x844 touch profile: all eight chips 44px, the card 144px, and
the description's box clear of the action cluster. Both are asserted in the
phone-viewport and touch-action scenarios.
2026-09-18 17:29:39 +02:00

294 lines
13 KiB
TypeScript

import { devices, expect, test } from '@playwright/test';
import type { Locator, Page } from '@playwright/test';
import { openAgentBuilder } from '../agents.helpers';
const TOOL_LIBRARY = 'Tool Library';
/** The dialog's own open animation moves it by a fraction of a pixel per frame,
* so geometry is only meaningful once two consecutive reads agree. */
const STABLE_EPSILON = 0.5;
const EDGE_TOLERANCE = 1;
type Box = { x: number; y: number; width: number; height: number };
async function settledBox(locator: Locator): Promise<Box> {
const last: { box: Box | null } = { box: null };
await expect
.poll(
async () => {
const box = await locator.boundingBox();
if (!box) {
return false;
}
const previous = last.box;
last.box = box;
return (
previous !== null &&
Math.abs(box.x - previous.x) < STABLE_EPSILON &&
Math.abs(box.y - previous.y) < STABLE_EPSILON &&
Math.abs(box.width - previous.width) < STABLE_EPSILON &&
Math.abs(box.height - previous.height) < STABLE_EPSILON
);
},
{ timeout: 15000 },
)
.toBe(true);
return last.box!;
}
async function openToolLibrary(page: Page): Promise<Locator> {
const form = await openAgentBuilder(page);
await form.getByRole('button', { name: 'Add tools' }).click();
const dialog = page.getByRole('dialog', { name: TOOL_LIBRARY });
await expect(dialog).toBeVisible();
return dialog;
}
/** The actions fade over the shared motion duration, so the resting value is
* what matters, not the frame the assertion happened to land on. */
async function expectOpacity(locator: Locator, value: string): Promise<void> {
await expect
.poll(() => locator.evaluate((element) => getComputedStyle(element).opacity), {
timeout: 10000,
})
.toBe(value);
}
async function blurAndMovePointer(page: Page): Promise<void> {
await page.evaluate(() => {
const active = document.activeElement;
if (active instanceof HTMLElement) {
active.blur();
}
});
await page.mouse.move(0, 0);
}
/** The dialog's close button is absolutely positioned over the search row, so the
* field has to stop short of it at every width. */
async function expectClearOfCloseButton(page: Page, dialog: Locator): Promise<void> {
const close = page.getByRole('dialog').locator('button.absolute.right-4');
if ((await close.count()) === 0) {
return;
}
const field = await dialog.getByRole('textbox', { name: 'Search tools…' }).boundingBox();
const button = await close.first().boundingBox();
expect(field).not.toBeNull();
expect(button).not.toBeNull();
const sameRow = field!.y < button!.y + button!.height && button!.y < field!.y + field!.height;
expect(sameRow && field!.x + field!.width > button!.x).toBe(false);
}
test.describe('tool library on a touch viewport', () => {
test.use({ viewport: devices['Pixel 7'].viewport, hasTouch: true });
test('@scenario:tool-library-fills-a-phone-viewport the catalog stays within a phone viewport', async ({
page,
}) => {
test.setTimeout(120000);
const dialog = await openToolLibrary(page);
const viewport = page.viewportSize();
expect(viewport).not.toBeNull();
const dialogBox = await settledBox(dialog);
expect(dialogBox.x).toBeLessThanOrEqual(EDGE_TOLERANCE);
expect(Math.abs(dialogBox.width - viewport!.width)).toBeLessThanOrEqual(EDGE_TOLERANCE);
await expect(dialog.locator('aside')).toHaveCount(0);
await expect(dialog.getByRole('group', { name: TOOL_LIBRARY })).toBeVisible();
/** The regression this pins: the dialog content is a grid, and without
* `min-w-0` its column sized to the chip row's 744px min-content, which
* pushed every card past the right edge of a 412px screen. */
const cards = dialog.getByRole('list', { name: TOOL_LIBRARY }).locator(':scope > li');
await expect(cards.first()).toBeVisible();
for (let index = 0; index < (await cards.count()); index += 1) {
const cardBox = await cards.nth(index).boundingBox();
expect(cardBox).not.toBeNull();
expect(cardBox!.x + cardBox!.width).toBeLessThanOrEqual(viewport!.width + EDGE_TOLERANCE);
}
expect(await page.evaluate(() => document.documentElement.scrollWidth)).toBe(viewport!.width);
/** The chip row is this layout's primary navigation and only a finger reaches
* it, so every chip owes the shared 44px tap-target floor. */
const chips = dialog.getByRole('group', { name: TOOL_LIBRARY }).getByRole('button');
for (let index = 0; index < (await chips.count()); index += 1) {
const chipBox = await chips.nth(index).boundingBox();
expect(chipBox).not.toBeNull();
expect(chipBox!.height).toBeGreaterThanOrEqual(44);
}
/** The close button is absolutely positioned over this row, so the search
* field owes it clearance; a responsive padding utility silently reset it. */
await expectClearOfCloseButton(page, dialog);
});
test('@scenario:tool-library-filter-chips-narrow-the-catalog filter chips narrow the catalog and expose an empty favorites state', async ({
page,
}) => {
test.setTimeout(120000);
const dialog = await openToolLibrary(page);
const cards = dialog.getByRole('list', { name: TOOL_LIBRARY }).locator(':scope > li');
const allChip = dialog.getByRole('button', { name: /^All(?:\s+\d+)?$/ });
await expect(allChip).toHaveAttribute('aria-pressed', 'true');
const allCount = await cards.count();
const mcpChip = dialog.getByRole('button', { name: /^MCP servers(?:\s+\d+)?$/ });
const mcpCount = Number.parseInt((await mcpChip.locator('span').last().innerText()).trim(), 10);
expect(mcpCount).toBeGreaterThan(0);
await mcpChip.click();
await expect.poll(() => cards.count()).toBe(mcpCount);
expect(await cards.count()).toBeLessThan(allCount);
await dialog.getByRole('button', { name: 'Favorites', exact: true }).click();
await expect(
dialog.getByText("You haven't favorited anything yet", { exact: true }),
).toBeVisible();
await expect(cards).toHaveCount(0);
});
test('@scenario:tool-card-actions-are-visible-without-hover-on-touch card actions are visible without hover on a coarse pointer', async ({
page,
}) => {
test.setTimeout(120000);
const dialog = await openToolLibrary(page);
await blurAndMovePointer(page);
const configure = dialog.getByRole('button', { name: 'Configure', exact: true }).first();
const favorite = dialog.getByRole('button', { name: 'Add to favorites', exact: true }).first();
await expect(configure).toBeVisible();
await expect(favorite).toBeVisible();
/** The reason the actions are visible: the hide rule is gated on the absence
* of a coarse pointer, not on the absence of hover. */
expect(await page.evaluate(() => matchMedia('(any-pointer: coarse)').matches)).toBe(true);
await expectOpacity(configure, '1');
await expectOpacity(favorite, '1');
/** The actions rest over the card's content, and on touch they never fade out,
* so the card has to keep its description clear of them. */
const overlap = await dialog
.locator('ul > li')
.first()
.evaluate((card) => {
const cluster = card.querySelector('div.absolute')?.getBoundingClientRect();
const paragraphs = Array.from(card.querySelectorAll('p'));
const description = paragraphs[paragraphs.length - 1]?.getBoundingClientRect();
if (!cluster || !description) {
return null;
}
return description.bottom > cluster.top && description.right > cluster.left;
});
expect(overlap).toBe(false);
});
test('@scenario:tool-row-actions-are-visible-without-hover-on-touch selected tool row actions stay visible without hover', async ({
page,
}) => {
test.setTimeout(120000);
const form = await openAgentBuilder(page);
await form.getByRole('button', { name: 'Add tools' }).click();
const dialog = page.getByRole('dialog', { name: TOOL_LIBRARY });
await expect(dialog).toBeVisible();
await dialog.getByRole('textbox', { name: 'Search tools…' }).fill('Calculator');
const calculator = dialog.getByRole('button', { name: /^Calculator/ }).first();
await expect(calculator).toBeVisible();
await calculator.click();
await page.keyboard.press('Escape');
await expect(dialog).not.toBeVisible();
const row = form.locator('li').filter({ hasText: 'Calculator' }).first();
await expect(row).toBeVisible();
const details = row.getByRole('button', { name: 'Tool details', exact: true });
const remove = row.getByRole('button', { name: 'Remove from agent', exact: true });
/** The row hides the whole action cluster, so the wrapper is what the gate
* applies to; a visible button inside a transparent parent is still invisible. */
const actionWrapper = details.locator('xpath=..');
await expect(details).toBeVisible();
await expect(remove).toBeVisible();
await expectOpacity(actionWrapper, '1');
});
});
/** A mouse device, asserted as one: these scenarios describe what a pointer that
* can hover and cannot tap sees, so they pin their own context rather than
* inheriting the run's project, one of which is a touch phone. */
test.describe('tool library on a mouse viewport', () => {
test.use({ viewport: { width: 1280, height: 860 }, hasTouch: false, isMobile: false });
test('@scenario:tool-card-actions-stay-hover-gated-with-a-mouse card actions remain hidden until hover on a mouse', async ({
page,
}) => {
test.setTimeout(120000);
const dialog = await openToolLibrary(page);
await blurAndMovePointer(page);
const configure = dialog.getByRole('button', { name: 'Configure', exact: true }).first();
const card = configure.locator('xpath=ancestor::li[1]');
expect(await page.evaluate(() => matchMedia('(any-pointer: coarse)').matches)).toBe(false);
await expectOpacity(configure, '0');
await card.hover();
await expectOpacity(configure, '1');
});
test('@scenario:tool-card-action-is-revealed-by-keyboard-focus keyboard focus reveals a card action', async ({
page,
}) => {
test.setTimeout(120000);
const dialog = await openToolLibrary(page);
await blurAndMovePointer(page);
const configure = dialog.getByRole('button', { name: 'Configure', exact: true }).first();
const card = configure.locator('xpath=ancestor::li[1]');
const cardButton = card.getByRole('button').first();
await cardButton.focus();
await cardButton.press('Tab');
await expect(configure).toBeFocused();
expect(await configure.evaluate((element) => element.matches(':focus-visible'))).toBe(true);
await expectOpacity(configure, '1');
});
test('@scenario:tool-library-keeps-its-rail-on-desktop the desktop rail contains kind entries', async ({
page,
}) => {
test.setTimeout(120000);
const dialog = await openToolLibrary(page);
const rail = dialog.locator('aside');
await expect(rail).toBeVisible();
for (const name of ['All', 'Native', 'Tools', 'MCP servers', 'Actions']) {
await expect(
rail.getByRole('button', { name: new RegExp(`^${name}(?:\\s+\\d+)?$`) }),
).toBeVisible();
}
await expect(dialog.getByRole('group', { name: TOOL_LIBRARY })).toHaveCount(0);
await expectClearOfCloseButton(page, dialog);
});
});
/** A narrow desktop window is below md as well, so it gets the chip row without
* getting a finger to drag it. */
test.describe('tool library in a narrow mouse window', () => {
test.use({ viewport: { width: 520, height: 900 }, hasTouch: false, isMobile: false });
test('@scenario:tool-library-chips-stay-scrollable-with-a-mouse the overflowing chip row keeps a scrollbar without touch', async ({
page,
}) => {
test.setTimeout(120000);
const dialog = await openToolLibrary(page);
const chips = dialog.getByRole('group', { name: TOOL_LIBRARY });
await expect(chips).toBeVisible();
expect(await page.evaluate(() => matchMedia('(any-pointer: coarse)').matches)).toBe(false);
const row = await chips.evaluate((element) => ({
overflows: element.scrollWidth > element.clientWidth,
scrollbar: element.offsetHeight - element.clientHeight,
}));
expect(row.overflows).toBe(true);
/** The affordance itself: with the scrollbar hidden this is 0 and a wheel
* scrolls the page instead, so the trailing views cannot be reached. */
expect(row.scrollbar).toBeGreaterThan(0);
/** And it does scroll: the last view has to become reachable. */
const favorites = chips.getByRole('button', { name: 'Favorites', exact: true });
await favorites.scrollIntoViewIfNeeded();
await favorites.click();
await expect(favorites).toHaveAttribute('aria-pressed', 'true');
});
});