An open source design system that's fully customizable and agent ready
TypeScript
feat(ChatLayout): the composer rides the software keyboard (#8176)
Christopher Chedeau695653f5d46f
diff --git a/.changeset/chat-layout-rides-the-keyboard.md b/.changeset/chat-layout-rides-the-keyboard.mdnew file mode 100644index 0000000000..4799a82d5e--- /dev/null+++ b/.changeset/chat-layout-rides-the-keyboard.md@@ -0,0 +1,8 @@+---+'@astryxdesign/core': patch+'@astryxdesign/cli': patch+---++[feat] ChatLayout keeps its composer on top of the software keyboard where the visual viewport shrinks for it, instead of leaving it underneath until the browser scrolls the whole page. In Chrome on Android the dock rides Gboard's measured slides up and down, in step with the keyboard. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. Where a page sets `interactive-widget=resizes-content`, Chrome shrinks the page for the keyboard itself and the composer stays above it without moving. A conversation at its newest message stays there, and the rest of the transcript can still be scrolled above the composer. On a touch screen, in a top-level page, every way into the composer's text (a tap, the keyboard's previous and next buttons, Tab, the input's `focus()`) reaches it without the page scrolling; under a mouse or inside an iframe the browser's own focus applies. In a top-level page on a touch screen, the composer's wrapper (without the scroll-to-bottom button) is a group with no name. When the keyboard's Done ends typing, focus rests there (it is no tab stop), so the next tap or Tab starts from the composer; it shows the focus ring after keyboard input only. A tap that focuses the composer still raises its click once. Under a mouse or inside an iframe, the wrapper is a plain container. Under Reduce Motion the composer never travels with Gboard: it cross-fades to its place above the keyboard. Under a mouse, with no software keyboard, nothing changes. The browser-support guide's section on the on-screen keyboard covers ChatLayout's composer.++@vjeuxdiff --git a/apps/storybook/stories/ChatLayout.stories.tsx b/apps/storybook/stories/ChatLayout.stories.tsxindex 77de43b386..4fcf950c18 100644--- a/apps/storybook/stories/ChatLayout.stories.tsx+++ b/apps/storybook/stories/ChatLayout.stories.tsx@@ -487,7 +487,14 @@ export const FullAIChat: StoryObj = {);return (- <div style={{height: '100vh', display: 'flex', flexDirection: 'column'}}>+ <div+ style={{+ // The visible height, less the 16px the preview pads every story+ // with on each side, so the composer rests on screen.+ height: 'calc(100dvh - 32px)',+ display: 'flex',+ flexDirection: 'column',+ }}><ChatLayout composer={composerEl}><ChatMessageList>{messages.map(msg => {@@ -832,7 +839,13 @@ export const PanelView: StoryObj = {export const WithEmptyState: StoryObj = {name: 'Empty State',render: () => (- <div style={{height: '100vh', display: 'flex', flexDirection: 'column'}}>+ <div+ style={{+ // The visible height, less the preview's 16px padding on each side.+ height: 'calc(100dvh - 32px)',+ display: 'flex',+ flexDirection: 'column',+ }}><ChatLayoutcomposer={<ChatComposer@@ -866,7 +879,8 @@ export const Densities: StoryObj = {style={{display: 'flex',gap: 16,- height: '100vh',+ // The visible height, less the preview's 16px padding on each side.+ height: 'calc(100dvh - 32px)',padding: 16,boxSizing: 'border-box',}}>diff --git a/docs/specs/AST-099-mobile-keyboard/spec.md b/docs/specs/AST-099-mobile-keyboard/spec.mdindex a23d802690..c9452a16e9 100644--- a/docs/specs/AST-099-mobile-keyboard/spec.md+++ b/docs/specs/AST-099-mobile-keyboard/spec.md@@ -331,8 +331,8 @@ No covered field meets FR9 on `main`. Each gap below is open.(`packages/core/src/keyboard/`) measures the keyboard, keeps focus frompanning the page, and keeps a focused field above the keyboard: it rides adocked container, scrolls a field's nearest scroller, and claims the first- tap. BottomSheet's Tall sheet reads it. No covered field reads it yet (Gaps- 2–9), and ChatLayout's dock does not (Gap 11).+ tap. BottomSheet's Tall sheet and ChatLayout's dock read it. No other+ covered field reads it yet (Gaps 2–8).- **Gap 2 — TextInput, TextArea, and NumberInput.** None has keyboard focushandling. In the page, only the browser's own reveal scroll brings the fieldinto view, and nothing proves it stays above the keyboard.@@ -358,25 +358,19 @@ No covered field meets FR9 on `main`. Each gap below is open.keyboard is `spec:AST-059`'s.- **Gap 8 — CommandPalette's search input.** It sits in a Dialog and has nokeyboard handling.-- **Gap 9 — ChatComposer's input.** ChatLayout docks the composer with a fixed- or sticky position at the bottom of the page, and neither the dock nor the- input applies the keyboard height, so on iOS the composer stays under the- keyboard. FR9 requires the dock to apply the height on its own element and- ride (Gap 11).- **Gap 10 — Fields in a fixed host the app builds.** A covered field in theapp's own fixed or sticky bottom bar, in a fixed Toolbar, or in a BottomSheetthat is not a fully expanded Tall sheet, has no handling that keeps it abovethe keyboard.-- **Gap 11 — The missing scroll range and ChatLayout's dock.** Partly met:+- **Gap 11 — The missing scroll range.** Partly met:the keyboard module moves an app's docked fixed container to the keyboard'stop, and scrolls a field's nearest scroller to put it 10 CSS px above thekeyboard in the frame the keyboard is reported(`packages/core/src/keyboard/keyboardTarget.ts`), but no covered field usesit yet (Gap 2). No field adds the missing scroll range at its scroller's end;until one does, an element that has nothing to scroll does not count as a- scroller (the field keeps the browser's own reveal). ChatLayout's dock does- not apply the keyboard height. BottomSheet's inset stays local to its own- sheet.+ scroller (the field keeps the browser's own reveal). BottomSheet's inset+ stays local to its own sheet.- **Gap 12 — A fully expanded sheet's hide in Firefox for Android.** Firefoxfor Android reports no keyboard slide, so the sheet takes the same path as inSafari on iOS (`packages/core/src/keyboard/useMobileKeyboard.ts`). But@@ -402,8 +396,11 @@ that sets its own `translate`, to the app.| FR7 | Tests in an iframe and in a top-level document | the same keyboard event sequence in both | A non-zero value or a claimed focus inside an iframe || FR8 | Chrome on Android in the emulator with Gboard, top-level document, plus a consumer documentation check | keyboard show and hide with the composer and a Tall sheet; a Lab bottom search field; reduced motion on; focus inside a keyboard-aware field, which rides by the visual-viewport height; an app with `interactive-widget=resizes-content`, focus inside and outside keyboard-aware fields, where a field's keyboard height is 0; Back: the ride starts at Chrome's hide report | A Core surface jumping after the keyboard settles, lagging the keyboard by more than a frame, left under the keyboard, moved by JavaScript per frame, or committing layout more than once; a Lab surface riding instead of committing at rest; anything travelling with the keyboard under reduced motion instead of DR2's cross-fade; the app's viewport setting overridden; a keyboard-aware field not riding by the visual-viewport height, or adding an offset under `interactive-widget=resizes-content`; or the setting missing from the docs || FR8 | Firefox for Android in the emulator, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |-| FR2–FR5 | Safari on iOS in the iOS Simulator or on a device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, in Safari and as a home-screen app | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom |+| FR2–FR5 | Safari on iOS in the iOS Simulator or on a device, top-level document | focus routes, keyboard shown and hidden, page panned and pinch-zoomed, a sheet moved, ChatLayout's composer, in Safari and as a home-screen app | The page lurches, the field ends under the keyboard, or the height is wrong after a pan or zoom || FR2–FR5 | Release gate: a physical iPhone in a top-level document (DEC-3) | iPhone Safari with the toolbar expanded and collapsed; iPhone home-screen app; the phone's refresh rate | The page lurches, the field ends under the keyboard, or the surface does not follow the keyboard |+| FR3–FR4 | ChatLayout's keyboard tests in jsdom and its interaction proofs in Chromium and WebKit | the fixed and the sticky dock with the keyboard shown and hidden; the message area's end padding; a transcript at its newest message; a page pinch-zoomed with the keyboard up; focus by tap, Tab, `focus()` and Done, under a finger and under a mouse | The dock left under the keyboard or lifted with none; the newest message unable to scroll above the composer; a transcript at its newest message left behind; the page panned to the composer's text under a finger; focus left in the text after Done, or the composer group focusable outside Done's park |+| FR8 | ChatLayout's interaction proofs in Chromium with Chrome's keyboard report | the dock riding Gboard's slide up from the report and down from the blur; reduced motion on | The dock lagging Gboard's slide, laying out or painting per frame, or jumping at the hand-back; the dock travelling under reduced motion instead of DR2's cross-fade |+| FR9 | ChatLayout's keyboard tests in jsdom | ChatComposer in the fixed and the sticky dock, above the keyboard after each focus route | ChatComposer ending under the keyboard, or moved a second time inside its dock, after any focus route || FR9 | TBD (Gap 1–11): a focus test per covered field, driving one keyboard change | each covered field in the page, a Tall and a `hug` BottomSheet, ChatLayout's fixed and sticky dock, an app's fixed bar docked to the bottom edge with no `translate` of its own, and a fixed Toolbar docked there; focus by tap, Tab, and `focus()`; a field in scrolling content in the page and in a nested scroller; a field near its scroller's end; a field in a scroller inside a full-viewport fixed container | A focused page field or Core-host field left under the keyboard or less than 10 CSS px above it (a field with no scroller between it and a fixed container FR9 leaves to the app keeps the browser's own reveal and is not a failure; a field that a scroller holds inside such a container, left under the keyboard, is a failure), a field in an app's docked bar whose bar's bottom does not meet the keyboard's top, scroll range left at the scroller's end after the keyboard hides, a page pan or translate, a reveal later than the frame the keyboard is reported in, or a second offset inside a host that already applies the height || FR9 | TBD (Gap 1): a source boundary check over the covered fields | every covered field's props type and source | A public prop, option, or context for the behavior || FR9 | TBD (Gap 1–11): Safari on iOS in the iOS Simulator and Chrome on Android in the emulator, top-level document | TextInput in the page, ChatComposer in its dock, a Selector search row in its sheet, and a TextInput in a fixed Toolbar | The field ends under the keyboard, or the page lurches |diff --git a/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json b/internal/eslint-plugin-astryx/no-comment-provenance.baseline.jsonindex 718f71e295..9d2ddbdcca 100644--- a/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json+++ b/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json@@ -126,10 +126,6 @@"FR5","FR6","INV10",- "INV11",- "INV11",- "architecture:theme-tokens",- "architecture:theme-tokens","spec:AST-086"],"packages/core/src/Chat/ChatComposerDrawer.tsx": ["#1182", "#2072"],diff --git a/packages/cli/assets/docs/browser-support.doc.mjs b/packages/cli/assets/docs/browser-support.doc.mjsindex 679ff89da9..b55a912125 100644--- a/packages/cli/assets/docs/browser-support.doc.mjs+++ b/packages/cli/assets/docs/browser-support.doc.mjs@@ -148,11 +148,11 @@ export const docs = {content: [{type: 'prose',- text: "On a phone, a fully expanded `height='tall'` BottomSheet responds to the on-screen keyboard: it measures the keyboard as the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, it keeps the focused field above the keyboard and leaves the page where it was. If Firefox for Android pans to the field, the sheet puts the page back within a couple of frames.",+ text: "On a phone, the components that respond to the on-screen keyboard, a fully expanded `height='tall'` BottomSheet and ChatLayout's composer, measure it the same way: the layout viewport's height minus the visual viewport's height times its scale. Where the visual viewport shrinks for the keyboard, as in Safari on iOS in the browser and as a home-screen app, in Firefox for Android and in Chrome on Android, they keep the focused field and the surface around it above the keyboard and leave the page where it was. If Firefox for Android pans to the field, they put the page back within a couple of frames.",},{type: 'prose',- text: 'In Chrome on Android, a Tall BottomSheet\u2019s focused field rides the keyboard as Gboard slides it up, and as Gboard slides it down after the field loses focus. The scroll room stays until the keyboard is down. A hide Chrome reports late, such as Back, which keeps the focus, rides down from Chrome\u2019s report. When the keyboard is reported, the sheet places the field just above it in that same frame, so Chrome has no covered field to pan to; if Chrome pans anyway, the sheet puts the page back when that pan ends. Chrome follows your viewport setting, which Astryx documents and never sets: your app owns its viewport `<meta>` element. By default (`interactive-widget=resizes-visual`) Chrome lays the keyboard over the page and pans to a focused field elsewhere on the page. With `interactive-widget=resizes-content` it shrinks the layout viewport instead, so content anchored to the bottom sits above the keyboard, and the sheet measures no keyboard and changes nothing: the browser has already made the room.',+ text: 'In Chrome on Android, ChatLayout\u2019s composer rides the keyboard as Gboard slides it up and down. A Tall BottomSheet\u2019s focused field rides the keyboard as Gboard slides it up, and as Gboard slides it down after the field loses focus. The scroll room stays until the keyboard is down. A hide Chrome reports late, such as Back, which keeps the focus, rides down from Chrome\u2019s report. When the keyboard is reported, the sheet places the field just above it in that same frame, so Chrome has no covered field to pan to; if Chrome pans anyway, the sheet puts the page back when that pan ends. Chrome follows your viewport setting, which Astryx documents and never sets: your app owns its viewport `<meta>` element. By default (`interactive-widget=resizes-visual`) Chrome lays the keyboard over the page and pans to a focused field elsewhere on the page. With `interactive-widget=resizes-content` it shrinks the layout viewport instead, so content anchored to the bottom sits above the keyboard, and those components measure no keyboard and change nothing: the browser has already made the room.',},{type: 'code',diff --git a/packages/core/src/Chat/ChatComposer.test.tsx b/packages/core/src/Chat/ChatComposer.test.tsxindex 77a11d96aa..b7b274088b 100644--- a/packages/core/src/Chat/ChatComposer.test.tsx+++ b/packages/core/src/Chat/ChatComposer.test.tsx@@ -1,12 +1,17 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {beforeEach, describe, it, expect, vi} from 'vitest';+import {afterEach, beforeEach, describe, it, expect, vi} from 'vitest';import {act, render, fireEvent, screen} from '@testing-library/react';import userEvent from '@testing-library/user-event';-import {StrictMode, useEffect, useRef} from 'react';+import {StrictMode, useEffect, useRef, type ReactNode} from 'react';import {ChatComposer} from './ChatComposer';-import {ChatComposerInput} from './ChatComposerInput';+import {+ ChatComposerInput,+ type ChatComposerInputHandle,+} from './ChatComposerInput';import {Tooltip} from '../Tooltip/Tooltip';+import {ChatLayout} from './ChatLayout';+import {KeyboardSurfaceContext} from './keyboardSurface';import {useChatComposerContext} from './ChatContext';import {createStaticSource} from '../Typeahead/createStaticSource';import {__resetInteractionModalityForTest} from '../utils/interactionModality';@@ -311,8 +316,146 @@ describe('ChatComposer input composition contract', () => {);const textarea = getByTestId('bare-textarea') as HTMLTextAreaElement;const body = textarea.parentElement!.parentElement!;+ const focus = vi.spyOn(textarea, 'focus');fireEvent.click(body);expect(document.activeElement).toBe(textarea);+ // Outside a keyboard-aware surface the browser's own focus applies.+ expect(focus).toHaveBeenCalledWith();+ });+});++describe('ChatComposer focus inside a keyboard-aware surface (spec:AST-099 FR4)', () => {+ // Under a finger, every route into the text refuses the browser's reveal,+ // which scrolls the whole page on iOS. Elsewhere, and under a mouse, the+ // browser's focus applies.+ const inSurface = (node: ReactNode) => (+ <KeyboardSurfaceContext value={true}>{node}</KeyboardSurfaceContext>+ );++ // The primary pointer `matchMedia` reports: a touch screen's coarse finger,+ // or a desktop's fine mouse.+ function primaryPointer(pointer: 'coarse' | 'fine') {+ vi.stubGlobal('matchMedia', (query: string) => ({+ matches: query === `(pointer: ${pointer})`,+ media: query,+ addEventListener: () => {},+ removeEventListener: () => {},+ }));+ }++ beforeEach(() => {+ primaryPointer('coarse');+ // A top-level document with a visual viewport, where the keyboard is+ // measured. jsdom has none of its own.+ Object.defineProperty(window, 'visualViewport', {+ configurable: true,+ value: Object.assign(new EventTarget(), {+ height: window.innerHeight,+ offsetTop: 0,+ scale: 1,+ }),+ });+ });++ afterEach(() => {+ Reflect.deleteProperty(window, 'visualViewport');+ vi.unstubAllGlobals();+ });++ it('focuses the default input on an empty-space tap without the reveal', () => {+ const {container} = render(inSurface(<ChatComposer onSubmit={() => {}} />));+ const editable = container.querySelector<HTMLElement>(+ '[contenteditable="true"]',+ )!;+ const focus = vi.spyOn(editable, 'focus');+ fireEvent.click(editable.parentElement!);+ expect(focus).toHaveBeenCalledWith({preventScroll: true});+ });++ it('focuses a bare field the shell falls back to without the reveal', () => {+ const {getByTestId} = render(+ inSurface(+ <ChatComposer+ onSubmit={() => {}}+ input={<textarea data-testid="bare-textarea" />}+ />,+ ),+ );+ const textarea = getByTestId('bare-textarea');+ const focus = vi.spyOn(textarea, 'focus');+ fireEvent.click(textarea.parentElement!.parentElement!);+ expect(focus).toHaveBeenCalledWith({preventScroll: true});+ });++ it('focuses without the reveal when the app calls the input\u2019s focus()', () => {+ let handle: ChatComposerInputHandle | null = null;+ const {container} = render(+ inSurface(+ <ChatComposerInput+ handleRef={h => {+ handle = h;+ }}+ />,+ ),+ );+ const editable = container.querySelector<HTMLElement>(+ '[contenteditable="true"]',+ )!;+ const focus = vi.spyOn(editable, 'focus');+ act(() => handle!.focus());+ expect(focus).toHaveBeenCalledWith({preventScroll: true});+ });++ it('keeps the browser\u2019s focus under a mouse (spec:AST-017 FR59)', () => {+ primaryPointer('fine');+ let handle: ChatComposerInputHandle | null = null;+ const {container} = render(+ inSurface(+ <ChatComposer+ onSubmit={() => {}}+ input={+ <ChatComposerInput+ handleRef={h => {+ handle = h;+ }}+ />+ }+ />,+ ),+ );+ const editable = container.querySelector<HTMLElement>(+ '[contenteditable="true"]',+ )!;+ const focus = vi.spyOn(editable, 'focus');+ act(() => handle!.focus());+ expect(focus).toHaveBeenCalledWith();+ expect(focus).not.toHaveBeenCalledWith({preventScroll: true});+ fireEvent.click(editable.parentElement!);+ expect(focus).not.toHaveBeenCalledWith({preventScroll: true});+ });++ it('keeps the browser\u2019s focus for a composer outside one', () => {+ const {container} = render(<ChatComposer onSubmit={() => {}} />);+ const editable = container.querySelector<HTMLElement>(+ '[contenteditable="true"]',+ )!;+ const focus = vi.spyOn(editable, 'focus');+ fireEvent.click(editable.parentElement!);+ expect(focus).toHaveBeenCalledWith();+ });++ it('is what ChatLayout gives its composer', () => {+ const {container} = render(+ <ChatLayout composer={<ChatComposer onSubmit={() => {}} />}>+ <p>Hello</p>+ </ChatLayout>,+ );+ const editable = container.querySelector<HTMLElement>(+ '[contenteditable="true"]',+ )!;+ const focus = vi.spyOn(editable, 'focus');+ fireEvent.click(editable.parentElement!);+ expect(focus).toHaveBeenCalledWith({preventScroll: true});});});diff --git a/packages/core/src/Chat/ChatComposer.tsx b/packages/core/src/Chat/ChatComposer.tsxindex 1619b92e9e..f34e03c86d 100644--- a/packages/core/src/Chat/ChatComposer.tsx+++ b/packages/core/src/Chat/ChatComposer.tsx@@ -24,6 +24,7 @@*/import React, {+ use,useState,useCallback,useRef,@@ -51,6 +52,10 @@ import {ChatComposerInput} from './ChatComposerInput';import {ChatComposerContext} from './ChatContext';import type {ChatComposerInputControl} from './ChatContext';import {ChatSendButton} from './ChatSendButton';+import {+ KeyboardSurfaceContext,+ focusInKeyboardSurface,+} from './keyboardSurface';import {themeProps} from '../utils/themeProps';import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';import {useMergedRefs} from '../hooks/useMergedRefs';@@ -263,7 +268,7 @@ const styles = stylex.create({backgroundColor: colorVars['--color-error-muted'],color: colorVars['--color-on-error-muted'],// Forced colors replace status fills with Canvas; this boundary keeps the- // fill's shape visible (architecture:theme-tokens INV11).+ // fill's shape visible.outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},outlineColor: {@@ -276,7 +281,7 @@ const styles = stylex.create({backgroundColor: colorVars['--color-warning-muted'],color: colorVars['--color-on-warning-muted'],// Forced colors replace status fills with Canvas; this boundary keeps the- // fill's shape visible (architecture:theme-tokens INV11).+ // fill's shape visible.outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},outlineColor: {@@ -433,31 +438,39 @@ export function ChatComposer(props: ChatComposerProps) {// drive it without knowing its DOM shape. Stable ref — safe in the memoized// context value.const inputControlRef = useRef<ChatComposerInputControl | null>(null);-- const handleBodyClick = useCallback((e: MouseEvent<HTMLDivElement>) => {- // Focus the input when clicking empty space in the body.- // Skip if the click target is a button, link, or interactive element.- const target = e.target as HTMLElement;- if (- target.closest(- 'button, a, [role="button"], [contenteditable="true"], [data-astryx-token]',- )- ) {- return;- }- // Prefer the input's registered control (works for any input shape,- // including editors whose focusable node isn't a bare- // contenteditable/textarea). Fall back to a DOM query so uninstrumented- // custom inputs still get click-to-focus.- if (inputControlRef.current) {- inputControlRef.current.focus();- return;- }- const editable = bodyRef.current?.querySelector<HTMLElement>(- '[contenteditable="true"], textarea',- );- editable?.focus();- }, []);+ // Inside ChatLayout's keyboard surface, a touch focus skips the browser's+ // reveal. Elsewhere the browser's own focus applies.+ const isKeyboardSurface = use(KeyboardSurfaceContext);++ const handleBodyClick = useCallback(+ (e: MouseEvent<HTMLDivElement>) => {+ // Focus the input when clicking empty space in the body.+ // Skip if the click target is a button, link, or interactive element.+ const target = e.target as HTMLElement;+ if (+ target.closest(+ 'button, a, [role="button"], [contenteditable="true"], [data-astryx-token]',+ )+ ) {+ return;+ }+ // Prefer the input's registered control (works for any input shape,+ // including editors whose focusable node isn't a bare+ // contenteditable/textarea). Fall back to a DOM query so uninstrumented+ // custom inputs still get click-to-focus.+ if (inputControlRef.current) {+ inputControlRef.current.focus();+ return;+ }+ const editable = bodyRef.current?.querySelector<HTMLElement>(+ '[contenteditable="true"], textarea',+ );+ if (editable) {+ focusInKeyboardSurface(editable, isKeyboardSurface);+ }+ },+ [isKeyboardSurface],+ );const handleBodyFocusCapture = useCallback((event: FocusEvent<HTMLDivElement>) => {diff --git a/packages/core/src/Chat/ChatComposerInput.tsx b/packages/core/src/Chat/ChatComposerInput.tsxindex 51c7ff8def..4a9d26cbc6 100644--- a/packages/core/src/Chat/ChatComposerInput.tsx+++ b/packages/core/src/Chat/ChatComposerInput.tsx@@ -28,6 +28,7 @@*/import {+ use,useRef,useState,useCallback,@@ -67,6 +68,10 @@ import {} from './useChatPasteAsToken';import {Badge, type BadgeProps} from '../Badge';import {useChatComposerContext} from './ChatContext';+import {+ KeyboardSurfaceContext,+ focusInKeyboardSurface,+} from './keyboardSurface';import {themeProps} from '../utils/themeProps';import {withholdCallerHandlers} from '../utils/disabledInteraction';import type {EnterKeyHint} from '../Field/textEntryTraits';@@ -437,6 +442,10 @@ export function ChatComposerInput(props: ChatComposerInputProps) {const insertTextRef = useRef<(text: string) => void>(() => {});const expandTokenRef = useRef<(id: string) => void>(() => {});+ // Inside ChatLayout's keyboard surface, every touch route into the text+ // skips the browser's reveal. Elsewhere the browser's own focus applies.+ const isKeyboardSurface = use(KeyboardSurfaceContext);+// A single handle object shared between the forwarded ref (via// `useImperativeHandle`) and `selfRef` (used by internal consumers// like paste-as-token). We can't rely on `useImperativeHandle`'s@@ -474,13 +483,13 @@ export function ChatComposerInput(props: ChatComposerInputProps) {// Read before focusing: `focus()` itself creates the offset-0 caret, so// asking afterwards cannot tell the user's own caret from the engine's.const existing = getSelectionRangeInside(editable);- editable.focus();+ focusInKeyboardSurface(editable, isKeyboardSurface);if (existing) {restoreSelectionRange(existing);return;}placeCaretAtEnd(editable);- }, []);+ }, [isKeyboardSurface]);/*** Focus the editable and put the caret after the draft, whatever the@@ -495,9 +504,9 @@ export function ChatComposerInput(props: ChatComposerInputProps) {if (!editable) {return;}- editable.focus();+ focusInKeyboardSurface(editable, isKeyboardSurface);placeCaretAtEnd(editable);- }, []);+ }, [isKeyboardSurface]);const handle: ChatComposerInputHandle = {insertToken: (token: ChatComposerToken) => insertTokenRef.current(token),diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjsindex 9a56754938..4c6aab35ab 100644--- a/packages/core/src/Chat/ChatLayout.doc.mjs+++ b/packages/core/src/Chat/ChatLayout.doc.mjs@@ -6,7 +6,7 @@ export const docs = {name: 'ChatLayout',subComponentOf: 'Chat',displayName: 'Chat Layout',- description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body.',+ description: 'Layout shell for full chat interfaces. Messages flow in normal page flow, composer is fixed to the bottom with a frosted glass dock. Set density (compact/balanced/spacious) to control spacing, message max-width, and blur layer sizing. Includes built-in auto-scroll, a "New messages" scroll-to-bottom button, and a frosted glass blur layer behind the composer. By default the layout root is the scroll container; pass scrollRef to delegate scrolling to a parent element or the document body. Where the visual viewport shrinks for the software keyboard, the composer stays on top of the keyboard, and a conversation at its newest message stays there. In Chrome on Android the composer rides Gboard\u2019s slides in step with them. In Safari on iOS (in the browser and as a home-screen app) and in Firefox for Android, it moves above the keyboard once the browser reports it. On a touch screen, in a top-level page, every way into the composer\u2019s text (a tap, the keyboard\u2019s previous and next buttons, Tab, the input\u2019s focus()) focuses it without scrolling the page; under a mouse or inside an iframe the browser\u2019s own focus applies. Where your page sets interactive-widget=resizes-content, Chrome on Android shrinks the page for the keyboard itself and the composer stays above it without moving (see the browser-support guide).',props: [{name: 'children',@@ -75,6 +75,10 @@ export const docs = {guidance: true,description: 'Use scrollRef when the chat is embedded in a page where a parent element handles scrolling.',},+ {+ guidance: true,+ description: "Give a full-page ChatLayout a container 100dvh tall, not 100vh: where a phone browser's toolbar collapses, 100vh is the viewport with the toolbar hidden, so the composer would start below the screen's edge.",+ },{guidance: false,description: "Don't apply a fixed height on the layout; let it fill its container with flex: 1.",@@ -93,7 +97,7 @@ export const docs = {{name: 'Frosted glass dock',required: true,- description: 'Sticky or fixed container at the bottom with a backdrop-blur layer. Houses the scroll button and composer.',+ description: 'Sticky or fixed container at the bottom with a backdrop-blur layer. Houses the scroll button and composer. While a software keyboard is up it sits on top of the keyboard, and the message area gets room to scroll above it.',},{name: 'Scroll-to-bottom button',@@ -103,7 +107,7 @@ export const docs = {{name: 'Composer',required: true,- description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer.',+ description: 'The input area for sending messages, typically ChatComposer. Docked at the bottom inside the frosted glass layer. In a top-level page on a touch screen, its wrapper (without the scroll button) is a group with no name. When the keyboard\u2019s Done ends typing, focus rests on that group (it is no tab stop), so the next tap or Tab starts from the composer. It shows the focus ring after keyboard input only. Under a mouse or inside an iframe, the wrapper is a plain container.',},{name: 'Empty state',@@ -117,7 +121,7 @@ export const docs = {export const docsZh = {name: 'ChatLayout',displayName: 'Chat Layout',- description: '完整聊天界面的布局外壳。消息在页面中自然流动,编写器固定在底部,带有毛玻璃效果。通过 density 属性控制密度。',+ description: '完整聊天界面的布局外壳。消息在页面中自然流动,编写器固定在底部,带有毛玻璃效果。通过 density 属性控制密度。在可视视口会随软键盘缩小的浏览器中,编写器停在键盘上方,停留在最新消息的对话保持在最新消息。在 Android 上的 Chrome 中,编写器随 Gboard 的滑动同步移动。在 iOS 上的 Safari(浏览器中和添加到主屏幕的网页应用)和 Android 上的 Firefox 中,编写器会在浏览器报告键盘后移到键盘上方。在触摸屏上的顶层页面中,进入编写器文本的每种方式(轻点、键盘的上一项和下一项按钮、Tab、输入框的 focus())都会聚焦它而不滚动页面;使用鼠标或在 iframe 中时沿用浏览器自身的聚焦行为。如果页面设置了 interactive-widget=resizes-content,Android 上的 Chrome 会自行为键盘缩小页面,编写器停在键盘上方而不移动(参见浏览器支持指南)。',propDescriptions: {children: '消息内容,通常是 ChatMessageList。在页面中自然流动。',composer: '编写器元素,通常是 ChatComposer。固定在底部,带有毛玻璃底座。',@@ -131,12 +135,13 @@ export const docsZh = {export const docsDense = {name: 'ChatLayout',displayName: 'Chat Layout',- description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body',+ description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; density prop (default balanced); scrollRef delegates to parent/body; in Chrome on Android (Gboard) the composer rides the software keyboard in step; in Safari on iOS and Firefox for Android it moves above the keyboard once reported (Chrome with interactive-widget=resizes-content: the page resizes, no move); transcript stays at newest msg, on a touch screen in a top-level page every focus route (tap, prev/next, Tab, focus()) w/o page scroll and Done rests focus on the composer group (no name, ring after keyboard input only, no tab stop); under a mouse or in an iframe: plain wrapper, browser focus',usage: {bestPractices: [{guidance: true, description: 'Pass ChatMessageList as children and ChatComposer as composer prop for complete chat.'},{guidance: true, description: 'Provide emptyState so new conversations show a prompt, not blank screen.'},{guidance: true, description: 'Use scrollRef when chat is embedded in a page where a parent element handles scrolling.'},+ {guidance: true, description: 'full-page: container 100dvh not 100vh (100vh = viewport w/ phone toolbar hidden; composer starts below screen edge)'},{guidance: false, description: 'Apply fixed height on layout; let it fill container with flex: 1.'},{guidance: false, description: 'Render multiple ChatLayout instances in same scroll container; each expects to own its scroll context.'},],diff --git a/packages/core/src/Chat/ChatLayout.tsx b/packages/core/src/Chat/ChatLayout.tsxindex af8b18fed0..4469396c2a 100644--- a/packages/core/src/Chat/ChatLayout.tsx+++ b/packages/core/src/Chat/ChatLayout.tsx@@ -4,7 +4,8 @@/*** @file ChatLayout.tsx- * @input Uses React, StyleX, theme tokens, useChatStreamScroll, useChatNewMessages+ * @input Uses React, StyleX, theme tokens, useChatStreamScroll, useChatNewMessages,+ * useChatKeyboard* @output Exports ChatLayout component and ChatLayoutProps* @position Layout shell for full chat interfaces — messages in page flow, composer fixed to bottom*@@ -19,6 +20,11 @@* self-scroll mode scrolls (#2573). In external-scrollRef mode the dock* is position: fixed (out of flow) and the message area fills the root.*+ * Software keyboard (useChatKeyboard): the dock rests above the keyboard.+ * The message area's end padding lets the newest message scroll above it.+ * Both follow the keyboard height, and the keyboard's own motion rides on+ * top. Every route into the composer's text skips Safari's page scroll.+ ** Density (compact/balanced/spacious) is controlled via a prop with* 'balanced' as the default. No JS measurement or ResizeObserver needed.* The container-type on root enables container queries in child components.@@ -31,13 +37,16 @@import {type ReactNode, useMemo, useRef} from 'react';import * as stylex from '@stylexjs/stylex';-import {spacingVars} from '../theme/tokens.stylex';+import {focusVars, spacingVars} from '../theme/tokens.stylex';+import {focusOutlineStyles} from '../utils/focusOutline.stylex';import type {BaseProps} from '../BaseProps';import {mergeProps} from '../utils';import {useChatStreamScroll} from './useChatStreamScroll';import {useChatNewMessages} from './useChatNewMessages';+import {useChatKeyboard} from './useChatKeyboard';import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';import {ChatLayoutContext} from './ChatContext';+import {KeyboardSurfaceContext} from './keyboardSurface';import {themeProps} from '../utils/themeProps';import {useMergedRefs} from '../hooks/useMergedRefs';@@ -142,6 +151,13 @@ const styles = stylex.create({paddingInline: 0,},+ // The end padding grows by the part of the keyboard over the dock. So the+ // newest message can scroll above the lifted composer, with no element+ // added for it.+ messageAreaKeyboard: (lift: number) => ({+ paddingBlockEnd: `calc(${spacingVars['--spacing-6']} + ${lift}px)`,+ }),+emptyState: {display: 'flex',alignItems: 'center',@@ -168,6 +184,11 @@ const styles = stylex.create({dockContainerSticky: {position: 'sticky',},+ // Rests the dock above the part of the keyboard that covers it+ // (useChatKeyboard's lift).+ dockLift: (lift: number) => ({+ bottom: lift,+ }),blurLayer: {position: 'absolute',@@ -190,6 +211,15 @@ const styles = stylex.create({paddingBlockEnd: spacingVars['--spacing-3'],},+ // The ring Done's park shows after typing, inside the dock's edge, which can+ // meet the viewport's.+ dockFocusRing: {+ outlineOffset: {+ default: null,+ ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,+ },+ },+dockInner: {marginInline: 'auto',width: '100%',@@ -315,6 +345,14 @@ export function ChatLayout({onResize: scroll.scrollIfLocked,});+ // --- Software keyboard ---+ const keyboard = useChatKeyboard({+ rootRef,+ scrollRef: scrollContainerRef,+ isSelfScrolling,+ scrollToBottom: scroll.scrollToBottom,+ });+const defaultScrollButton = (<ChatLayoutScrollButtonisVisible={scroll.isScrolledUp || newMsgs.hasNewMessages}@@ -377,7 +415,13 @@ export function ChatLayout({style,)}>{/* Message area */}- <div {...stylex.props(styles.messageArea, currentDensity.messageArea)}>+ <div+ ref={keyboard.messagesRef}+ {...stylex.props(+ styles.messageArea,+ currentDensity.messageArea,+ keyboard.lift > 0 && styles.messageAreaKeyboard(keyboard.lift),+ )}>{showEmpty && emptyState ? (<div {...stylex.props(styles.emptyState)}>{emptyState}</div>) : (@@ -387,11 +431,13 @@ export function ChatLayout({{/* Dock container — sticky/fixed, holds blur + scroll button + composer */}<div+ ref={keyboard.dockRef}{...stylex.props(styles.dockContainer,isSelfScrolling? styles.dockContainerSticky: styles.dockContainerFixed,+ keyboard.lift > 0 && styles.dockLift(keyboard.lift),)}>{/* Scroll-to-bottom button */}{scrollButton === undefined ? defaultScrollButton : scrollButton}@@ -399,12 +445,24 @@ export function ChatLayout({{/* Frosted glass layer */}<div {...stylex.props(styles.blurLayer, currentDensity.blurLayer)} />- {/* Composer */}- <div {...stylex.props(styles.dock, currentDensity.dock)}>- <div {...stylex.props(styles.dockInner, currentDensity.dockInner)}>- {composer}+ {/* The composer's region. Under a finger in a top-level page,+ useChatKeyboard makes it a group with no name, where focus rests+ after the keyboard's Done. Elsewhere it is a plain container. */}+ <KeyboardSurfaceContext value={true}>+ <div+ ref={keyboard.composerRef}+ {...stylex.props(+ focusOutlineStyles.focusVisible,+ styles.dock,+ currentDensity.dock,+ styles.dockFocusRing,+ )}>+ <div+ {...stylex.props(styles.dockInner, currentDensity.dockInner)}>+ {composer}+ </div></div>- </div>+ </KeyboardSurfaceContext></div></div></ChatLayoutContext>diff --git a/packages/core/src/Chat/__tests__/ChatLayoutKeyboard.interaction.browser.spec.ts b/packages/core/src/Chat/__tests__/ChatLayoutKeyboard.interaction.browser.spec.tsnew file mode 100644index 0000000000..c7a44f5780--- /dev/null+++ b/packages/core/src/Chat/__tests__/ChatLayoutKeyboard.interaction.browser.spec.ts@@ -0,0 +1,908 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file ChatLayoutKeyboard.interaction.browser.spec.ts+ * @input The built "Full AI Chat" ChatLayout story, a stand-in visual+ * viewport that reports a software keyboard, real touch input and the+ * interaction harness+ * @output Proofs that on Chrome's profile the dock rides Gboard's slide up+ * and down with no Layout or Paint per frame. Under Reduce Motion it never+ * travels, also on a hide reported in steps. The transcript stays at its+ * newest message. A tap on the composer's text scrolls no page. Done's park+ * shows the focus ring after typing only. A storyboard shows the rise+ * @position Browser proofs for Chat/useChatKeyboard.ts and+ * keyboard/keyboardLayoutGuide.ts. Headless browsers have no software+ * keyboard, so the test shrinks the page's `visualViewport` as Mobile+ * Safari does: one `resize`, to the final height+ */++import {+ expect,+ test,+ type Locator,+ type Page,+} from '@astryxdesign/a11y-spec/playwright';+import {cubicBezier} from '../../motion/bezier';+import {keyboard as ANDROID_KEYBOARD} from '../../motion/android/keyboard';+import {+ animationStoryboard,+ compareCurve,+ countBetween,+ curveOf,+ holdAnimations,+ type HeldAnimation,+ openStory,+ releaseAnimations,+ sampleCurve,+ timeline,+ touchDriver,+ traceRendering,+ waitForAnimation,+ waitForRest,+ withStorybook,+} from '@astryxdesign/interaction-harness';++const storybook = withStorybook(test);+// The cover Mobile Safari reports on an iPhone 17 Pro (keyboard, accessory+// bar and the floating address bar over a 714 px layout viewport).+const COVER = 337;++/**+ * Replaces `window.visualViewport` before the page loads with one the test+ * drives: `__keyboard(cover)` shrinks it from the bottom and fires one+ * `resize`, as Mobile Safari does.+ */+async function installKeyboard(page: Page) {+ await page.addInitScript(() => {+ // Mobile Safari has no VirtualKeyboard API, so the keyboard layout guide+ // publishes no slide there.+ Reflect.deleteProperty(Navigator.prototype, 'virtualKeyboard');+ const viewport = Object.assign(new EventTarget(), {+ height: window.innerHeight,+ width: window.innerWidth,+ offsetTop: 0,+ offsetLeft: 0,+ pageTop: 0,+ pageLeft: 0,+ scale: 1,+ });+ Object.defineProperty(window, 'visualViewport', {+ configurable: true,+ get: () => viewport,+ });+ (window as unknown as {__keyboard: (cover: number) => void}).__keyboard =+ cover => {+ viewport.height = window.innerHeight - cover;+ viewport.dispatchEvent(new Event('resize'));+ };+ });+}++/**+ * Chrome on Android: the visual viewport the test drives, and a+ * VirtualKeyboard object the guide must leave alone, so the guide reads+ * Chrome's profile. It runs under a finger, as Chrome on Android does, so the+ * composer's focus routes are the touch ones.+ */+async function installAndroidKeyboard(page: Page) {+ await page.addInitScript(() => {+ const keyboard = Object.assign(new EventTarget(), {+ overlaysContent: false,+ boundingRect: new DOMRect(0, 0, 0, 0),+ });+ Object.defineProperty(navigator, 'virtualKeyboard', {+ configurable: true,+ value: keyboard,+ });+ const viewport = Object.assign(new EventTarget(), {+ height: window.innerHeight,+ width: window.innerWidth,+ offsetTop: 0,+ offsetLeft: 0,+ pageTop: 0,+ pageLeft: 0,+ scale: 1,+ });+ Object.defineProperty(window, 'visualViewport', {+ configurable: true,+ get: () => viewport,+ });+ (window as unknown as {__keyboard: (cover: number) => void}).__keyboard =+ cover => {+ viewport.height = window.innerHeight - cover;+ viewport.dispatchEvent(new Event('resize'));+ };+ });+}++interface Chat {+ dock: Locator;+ messages: Locator;+ editable: Locator;+ /**+ * How far the dock rises for COVER: until its resting bottom (the root's+ * bottom edge, which may sit below the layout viewport's) clears the cover.+ */+ lift: number;+}++async function openChat(+ page: Page,+ {android = false}: {android?: boolean} = {},+): Promise<Chat> {+ if (android) {+ await installAndroidKeyboard(page);+ } else {+ await installKeyboard(page);+ }+ await openStory(page, storybook(), 'core-chatlayout--full-ai-chat');+ const editable = page.locator('[contenteditable="true"]').first();+ await expect(editable).toBeVisible();+ // Name the dock (the sticky container around the composer) and the+ // message area for the locators below.+ await editable.evaluate(element => {+ let dock: HTMLElement | null = element as HTMLElement;+ while (dock != null && getComputedStyle(dock).position !== 'sticky') {+ dock = dock.parentElement;+ }+ dock?.setAttribute('data-testid', 'keyboard-dock');+ dock?.parentElement?.firstElementChild?.setAttribute(+ 'data-testid',+ 'keyboard-messages',+ );+ });+ const dock = page.getByTestId('keyboard-dock');+ const messages = page.getByTestId('keyboard-messages');+ // The story opens at its newest message.+ await page.waitForTimeout(300);+ const lift = await dock.evaluate(+ (el, cover) =>+ (el.parentElement as HTMLElement).getBoundingClientRect().bottom -+ (window.innerHeight - cover),+ COVER,+ );+ return {dock, messages, editable, lift};+}++const showKeyboard = async (page: Page, cover = COVER) =>+ page.evaluate(+ c => (window as unknown as {__keyboard: (c: number) => void}).__keyboard(c),+ cover,+ );++// Where the dock is drawn relative to its rest without a keyboard, CSS px,+// negative up. It is its presented vertical `translate`, less the `bottom`+// offset the layout gives it from the keyboard height. The animator moves the+// individual property, not `transform`.+const dockY = async (dock: Locator) => dock.evaluate(presentedY);++// How far above the bottom of the transcript's scrollport the dock is drawn:+// 0 at rest with no keyboard. A sticky dock leaves the bottom when the+// content ends inside the scrollport. A translate or a late scroll clamp can+// cause that, and the dock's styles alone would not show it.+const dockGap = async (dock: Locator) =>+ dock.evaluate(+ el =>+ (el.parentElement as HTMLElement).getBoundingClientRect().bottom -+ el.getBoundingClientRect().bottom,+ );++function presentedY(el: Element): number {+ const style = getComputedStyle(el);+ const translate =+ style.translate === 'none'+ ? 0+ : parseFloat(style.translate.split(' ')[1] ?? '0') || 0;+ const bottom =+ style.position === 'sticky' || style.position === 'fixed'+ ? parseFloat(style.bottom) || 0+ : 0;+ return translate - bottom;+}++test('one keyboard change reads the layout once, however many read the height (architecture:react-component-runtime INV11)', async ({+ page,+}) => {+ const {dock, editable} = await openChat(page);+ await editable.focus();+ const reads = await page.evaluate(async cover => {+ // Count every read of the visual viewport's height from here on: the+ // keyboard module's one measurement per report.+ const viewport = window.visualViewport as unknown as {height: number};+ let height = viewport.height;+ let count = 0;+ Object.defineProperty(viewport, 'height', {+ configurable: true,+ get: () => {+ count += 1;+ return height;+ },+ set: (value: number) => {+ height = value;+ },+ });+ (window as unknown as {__keyboard: (c: number) => void}).__keyboard(cover);+ // The guide, the hook and the ride's commit all run by the next frame.+ await new Promise(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(resolve)),+ );+ return count;+ }, COVER);+ await waitForRest(dock);+ expect(reads).toBe(1);+});++test('the lift is the part of the keyboard over the dock\u2019s resting bottom: a root ending below the viewport rises by more than the cover', async ({+ page,+}) => {+ const {dock, editable} = await openChat(page);+ // A root that ends below the layout viewport: the viewport's full height+ // under the preview's 16 px gutter.+ await dock.evaluate(el => {+ const root = el.parentElement as HTMLElement;+ (root.parentElement as HTMLElement).style.height = '100vh';+ });+ await page.waitForTimeout(200);+ const lift = await dock.evaluate(+ (el, cover) =>+ (el.parentElement as HTMLElement).getBoundingClientRect().bottom -+ (window.innerHeight - cover),+ COVER,+ );+ expect(lift).toBeGreaterThan(COVER);+ await editable.focus();+ await showKeyboard(page);+ await waitForRest(dock);+ await page.waitForTimeout(100);+ const dockBottom = await dock.evaluate(+ el => el.getBoundingClientRect().bottom,+ );+ const keyboardTop = await page.evaluate(c => window.innerHeight - c, COVER);+ expect(dockBottom).toBeCloseTo(keyboardTop, 0);+});++test('a page with room under the chat: the dock rises only by the part of the keyboard that reaches it, and not at all when none does', async ({+ page,+}) => {+ const {dock, editable} = await openChat(page);+ // Leave 200 px of page under the chat's root.+ const room = 200;+ await dock.evaluate((el, r) => {+ const root = el.parentElement as HTMLElement;+ (root.parentElement as HTMLElement).style.height = `calc(100vh - ${r}px)`;+ }, room);+ await page.waitForTimeout(200);+ const restingBottom = await dock.evaluate(+ el => (el.parentElement as HTMLElement).getBoundingClientRect().bottom,+ );+ await editable.focus();+ await showKeyboard(page);+ await waitForRest(dock);+ await page.waitForTimeout(100);+ const expected = await page.evaluate(+ ([c, b]) => Math.max(0, b - (window.innerHeight - c)),+ [COVER, restingBottom],+ );+ expect(expected).toBeGreaterThan(0);+ expect(expected).toBeLessThan(COVER);+ expect(await dockY(dock)).toBeCloseTo(-expected, 0);+ expect(+ await dock.evaluate(el => el.getBoundingClientRect().bottom),+ ).toBeCloseTo(await page.evaluate(c => window.innerHeight - c, COVER), 0);++ // A keyboard that stops short of the chat's bottom moves nothing.+ const short = Math.floor(+ await page.evaluate(b => window.innerHeight - b - 20, restingBottom),+ );+ await showKeyboard(page, short);+ await waitForRest(dock);+ await page.waitForTimeout(100);+ expect(await dockY(dock)).toBeCloseTo(0, 0);+});++test('in a vertical writing mode the lift stays on the physical bottom, where the keyboard is', async ({+ page,+}) => {+ const {dock, editable, lift} = await openChat(page);+ // A logical inset-block-end would map to left under vertical-rl; the+ // on-screen keyboard is still at the bottom of the screen.+ await dock.evaluate(el => {+ (el.parentElement as HTMLElement).style.writingMode = 'vertical-rl';+ });+ await editable.focus();+ await showKeyboard(page);+ await page.waitForTimeout(1200);+ const style = await dock.evaluate(el => {+ const computed = getComputedStyle(el);+ return {+ bottom: computed.bottom,+ left: computed.left,+ right: computed.right,+ };+ });+ expect(parseFloat(style.bottom)).toBeCloseTo(lift, 0);+ expect(style.left).toBe('auto');+ expect(style.right).toBe('auto');+});++test('the transcript at its newest message stays there', async ({page}) => {+ const {dock, lift} = await openChat(page);+ const atEnd = async () =>+ dock.evaluate(el => {+ const scroller = el.parentElement as HTMLElement;+ return (+ scroller.scrollHeight - scroller.scrollTop - scroller.clientHeight < 2+ );+ });+ expect(await atEnd()).toBe(true);+ await showKeyboard(page);+ await waitForRest(dock);+ expect(await atEnd()).toBe(true);+ expect(await dockY(dock)).toBeCloseTo(-lift, 0);+});++test.describe('under a mouse', () => {+ // A desktop browser: the primary pointer is fine (the projects emulate a+ // phone).+ test.use({hasTouch: false, isMobile: false});++ test('a click in the dock beside the composer does not focus the composer group (spec:AST-017 FR59)', async ({+ page,+ }) => {+ const {dock, editable} = await openChat(page);+ await editable.click();+ // The composer region: the dock's last box, a plain container under a+ // mouse.+ const region = dock.locator(':scope > div').last();+ await expect(region).not.toHaveAttribute('role', 'group');+ const outer = await region.boundingBox();+ const inner = await region.locator(':scope > div').boundingBox();+ if (outer == null || inner == null) {+ throw new Error('the composer region is not laid out');+ }+ // The region's own gutter, beside the composer.+ const gutter = inner.x - outer.x;+ expect(gutter).toBeGreaterThan(2);+ await page.mouse.click(outer.x + gutter / 2, inner.y + inner.height / 2);+ expect(+ await region.evaluate(element => element === document.activeElement),+ ).toBe(false);+ });+});++test('the dock comes down when the composer text loses focus', async ({+ page,+}) => {+ const {dock, editable} = await openChat(page);+ await editable.focus();+ await showKeyboard(page);+ await waitForRest(dock);+ await editable.evaluate(el => (el as HTMLElement).blur());+ // The hide starts from the blur; Mobile Safari reports it once the+ // keyboard is down.+ await waitForAnimation(dock);+ await page.waitForTimeout(440);+ await showKeyboard(page, 0);+ await waitForRest(dock);+ await page.waitForTimeout(100);+ expect(await dockY(dock)).toBeCloseTo(0, 0);+ // Drawn at the bottom, not where the transcript ends.+ expect(await dockGap(dock)).toBeCloseTo(0, 0);+});++test('a hide the home-screen app reports early: the dock rests at the bottom once the layout takes over', async ({+ page,+}) => {+ const {dock, editable} = await openChat(page);+ await editable.focus();+ await showKeyboard(page);+ await waitForRest(dock);+ await page.waitForTimeout(300);+ await editable.evaluate(async el => {+ (el as HTMLElement).blur();+ await new Promise(resolve => setTimeout(resolve, 30));+ (window as unknown as {__keyboard: (c: number) => void}).__keyboard(0);+ });+ await page.waitForTimeout(1200);+ expect(await dockY(dock)).toBeCloseTo(0, 0);+ expect(await dockGap(dock)).toBeCloseTo(0, 0);+});++test('a tap on the composer text focuses it without scrolling the page', async ({+ page,+}) => {+ const {editable} = await openChat(page);+ const driver = await touchDriver(page);+ const box = await editable.boundingBox();+ if (box == null) {+ throw new Error('no editable');+ }+ const before = await page.evaluate(() => ({+ x: window.scrollX,+ y: window.scrollY,+ }));+ await driver.tap({x: box.x + 24, y: box.y + box.height / 2});+ await expect(editable).toBeFocused();+ const after = await page.evaluate(() => ({+ x: window.scrollX,+ y: window.scrollY,+ }));+ expect(after).toEqual(before);+});++test.describe('under a finger', () => {+ test.use({hasTouch: true, isMobile: true});++ test('the browser\u2019s own reveal pan is put back: the composer rests on the keyboard and the page does not move (spec:AST-099 FR4)', async ({+ page,+ }) => {+ const {dock, editable} = await openChat(page);+ await editable.focus();+ await showKeyboard(page);+ await page.waitForTimeout(150);+ const result = await page.evaluate(async cover => {+ const viewport = window.visualViewport as unknown as EventTarget & {+ offsetTop: number;+ };+ // The browser's side of a put-back: scrolling a fixed element's top+ // into view pans the visual viewport to it.+ let putBacks = 0;+ const original = Element.prototype.scrollIntoView;+ Element.prototype.scrollIntoView = function (+ this: Element,+ ...args: Parameters<Element['scrollIntoView']>+ ) {+ if (getComputedStyle(this).position === 'fixed') {+ putBacks += 1;+ viewport.offsetTop = Math.max(0, this.getBoundingClientRect().top);+ }+ original.apply(this, args);+ };+ // As Chrome 124 does while the composer is still riding up: it pans+ // the visual viewport to the composer by the keyboard's height.+ viewport.offsetTop = cover;+ viewport.dispatchEvent(new Event('scroll'));+ await new Promise(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(resolve)),+ );+ Element.prototype.scrollIntoView = original;+ return {putBacks, offsetTop: viewport.offsetTop};+ }, COVER);+ await waitForRest(dock);+ expect(result.putBacks).toBeGreaterThan(0);+ expect(result.offsetTop).toBe(0);+ });++ test('after typing, Done parks focus on the composer group, which shows the shared focus ring (architecture:interaction-modality INV1)', async ({+ page,+ }) => {+ const {dock, editable} = await openChat(page);+ await editable.focus();+ await page.keyboard.type('Hi');+ // Done blurs the composer's text, and focus goes to nothing.+ await editable.evaluate(element => (element as HTMLElement).blur());+ const region = dock.locator(':scope > div').last();+ await expect(region).toHaveAttribute('role', 'group');+ await expect(region).toBeFocused();+ const ring = await region.evaluate(element => {+ const style = getComputedStyle(element);+ return {style: style.outlineStyle, width: parseFloat(style.outlineWidth)};+ });+ expect(ring.style).not.toBe('none');+ expect(ring.width).toBeGreaterThan(0);+ });++ test('after a tap and no typing, Done parks focus on the composer group with no focus ring (architecture:interaction-modality INV1)', async ({+ page,+ }) => {+ const {dock, editable} = await openChat(page);+ await editable.tap();+ await expect(editable).toBeFocused();+ // Done blurs the composer's text, and focus goes to nothing.+ await editable.evaluate(element => (element as HTMLElement).blur());+ const region = dock.locator(':scope > div').last();+ await expect(region).toBeFocused();+ const ring = await region.evaluate(element => {+ const style = getComputedStyle(element);+ return {style: style.outlineStyle, width: parseFloat(style.outlineWidth)};+ });+ expect(ring.style === 'none' || ring.width === 0).toBe(true);+ });+});++// The dock's ride among the animations a hold takes on the dock: the one+// script animation that moves `translate`. A CSS transition that starts at+// the blur comes too. Its samples count from its own start, `offsetMs` after+// the hold's earliest start.+function rideOf(held: ReadonlyArray<HeldAnimation>): HeldAnimation {+ const ride = held.find(+ a => a.kind === 'Animation' && a.keyframes.some(k => 'translate' in k),+ );+ if (ride == null) {+ throw new Error(`no ride among ${JSON.stringify(held)}`);+ }+ return ride;+}++test.describe('Chrome on Android (spec:AST-099 FR8)', () => {+ test.use({hasTouch: true, isMobile: true});+ test.skip(+ ({browserName}) => browserName !== 'chromium',+ 'Chrome’s keyboard profile needs the VirtualKeyboard API',+ );++ const reportAt = async (page: Page, cover: number) =>+ page.evaluate(c => {+ let at = 0;+ const view = window.visualViewport as unknown as EventTarget;+ view.addEventListener(+ 'resize',+ event => {+ at = event.timeStamp;+ },+ {once: true},+ );+ (window as unknown as {__keyboard: (c: number) => void}).__keyboard(c);+ return at;+ }, cover);++ test('the rise does no Layout or Paint per frame', async ({page}) => {+ const {editable} = await openChat(page, {android: true});+ await editable.focus();+ // Focus starts the composer's own feedback, a short box-shadow transition+ // that paints every frame. It is no part of the ride, so it ends before+ // the trace, and the window counts the ride alone.+ await page.evaluate(async () => {+ const transitions = document+ .getAnimations()+ .filter(animation => animation instanceof CSSTransition);+ await Promise.all(+ transitions.map(async transition =>+ transition.finished.catch(() => undefined),+ ),+ );+ });+ // Records each ride the motion engine starts on the dock, when it starts+ // and when it is cancelled. Reading an animation's times reads no layout.+ // The engine sets the start in the task that makes the ride, so a+ // microtask reads it. A promise on `ready` would add a main-thread frame+ // when the compositor starts the ride.+ await page.evaluate(() => {+ const dock = document.querySelector('[data-testid="keyboard-dock"]');+ const rides: {start: number | null; cancelled: number | null}[] = [];+ (window as unknown as {__rides: typeof rides}).__rides = rides;+ const animate = Element.prototype.animate;+ Element.prototype.animate = function (+ this: Element,+ keyframes: Keyframe[] | PropertyIndexedKeyframes | null,+ options?: number | KeyframeAnimationOptions,+ ) {+ const animation = animate.call(this, keyframes, options);+ if (+ this === dock &&+ Array.isArray(keyframes) &&+ keyframes.some(keyframe => 'translate' in keyframe)+ ) {+ const ride = {+ start: null as number | null,+ cancelled: null as number | null,+ };+ rides.push(ride);+ queueMicrotask(() => {+ if (animation.startTime != null) {+ ride.start = performance.timeOrigin + Number(animation.startTime);+ }+ });+ animation.addEventListener('cancel', () => {+ ride.cancelled = performance.timeOrigin + performance.now();+ });+ }+ return animation;+ };+ });+ // No polling inside the trace: reading a sticky element's presented style+ // from the test forces a layout every frame by itself.+ let reported = 0;+ const trace = await traceRendering(page, async () => {+ reported = await page.evaluate(async cover => {+ const from = performance.timeOrigin + performance.now();+ (window as unknown as {__keyboard: (c: number) => void}).__keyboard(+ cover,+ );+ await new Promise(resolve => setTimeout(resolve, 400));+ return from;+ }, COVER);+ });+ // The steady part of Gboard's slide, 125–220 ms after the report. Its start+ // lays out once and paints in its first two frames. From about 230 ms, its+ // end paints twice and hands the layers back with one layout.+ const steady = {from: reported + 125, to: reported + 220};+ // A ride runs through that window: it starts before the window, its slide+ // ends after it, and nothing cancels it sooner. So no rendering in the+ // window means the dock rode without it, not that nothing moved.+ const rides = await page.evaluate(+ () =>+ (+ window as unknown as {+ __rides: {start: number | null; cancelled: number | null}[];+ }+ ).__rides,+ );+ const riding = rides.some(+ ({start, cancelled}) =>+ start != null &&+ start <= steady.from &&+ start + ANDROID_KEYBOARD.showMs >= steady.to &&+ (cancelled == null || cancelled >= steady.to),+ );+ expect(riding, JSON.stringify({reported, rides})).toBe(true);+ const during = countBetween(trace, steady.from, steady.to);+ // On failure, every rendering event of the rise and the long tasks, in ms+ // after the report.+ const detail = JSON.stringify({+ during,+ events: trace.events+ .filter(e => e.t >= reported - 20 && e.t <= reported + 400)+ .map(e => `${e.name}@${Math.round(e.t - reported)}`),+ longTasks: trace.longTasks.map(+ task =>+ `${Math.round(task.start - reported)}+${Math.round(task.durationMs)}`,+ ),+ });+ expect(during.Layout ?? 0, detail).toBe(0);+ expect(during.Paint ?? 0, detail).toBe(0);+ });++ test(+ 'storyboard: the keyboard shows and the composer rides Gboard’s slide',+ {tag: '@storyboard'},+ async ({page}, testInfo) => {+ const {dock, editable, messages, lift} = await openChat(page, {+ android: true,+ });+ const viewport = page.viewportSize() ?? {width: 402, height: 714};+ await editable.focus();+ await reportAt(page, COVER);+ await waitForAnimation(dock);+ const {storyboard} = await animationStoryboard(page, {+ name: 'chatlayout-keyboard-show',+ judges: {target: dock, property: 'translate'},+ clip: {x: 0, y: 0, width: viewport.width, height: viewport.height},+ times: timeline(300, 300 / 12),+ columns: 6,+ cellScale: 0.4,+ measure: async () => ({+ dockY: await dockY(dock),+ messagesY: await dockY(messages),+ }),+ });+ await storyboard.write(testInfo);+ const trace = storyboard.frames.map(f => f.data as {dockY: number});+ // The dock only ever rises during the show, ending at the cover.+ for (let i = 1; i < trace.length; i += 1) {+ expect(trace[i].dockY).toBeLessThanOrEqual(trace[i - 1].dockY + 0.01);+ }+ expect(trace.at(-1)?.dockY).toBeCloseTo(-lift, 0);+ },+ );++ test('the dock rides up on Gboard’s slide from the report, dated back to Gboard’s start', async ({+ page,+ }) => {+ const {dock, editable, lift} = await openChat(page, {android: true});+ await editable.focus();+ const reported = await reportAt(page, COVER);+ await waitForAnimation(dock);+ const start = await dock.evaluate(el =>+ Math.max(+ ...el.getAnimations().map(a => Number(a.startTime ?? -Infinity)),+ ),+ );+ expect(+ Math.abs(start - (reported - ANDROID_KEYBOARD.showReportLagMs)),+ ).toBeLessThan(2);+ const ride = rideOf(+ await holdAnimations(page, dock, {+ judges: {target: dock, property: 'translate'},+ }),+ );+ const samples = curveOf(+ await sampleCurve(dock, timeline(ride.offsetMs + ride.curveEndMs)),+ 'translateY',+ );+ await releaseAnimations(page);+ const ease = cubicBezier(ANDROID_KEYBOARD.showCurve);+ const result = compareCurve(+ samples,+ t =>+ -lift *+ ease(+ Math.min(+ 1,+ Math.max(0, (t - ride.offsetMs) / ANDROID_KEYBOARD.showMs),+ ),+ ),+ 0.5,+ );+ expect(result.maxError, JSON.stringify(result.worst)).toBeLessThanOrEqual(+ 0.5,+ );+ // And the layout takes the lift once the ride ends.+ await waitForRest(dock);+ await page.waitForTimeout(100);+ expect(await dockY(dock)).toBeCloseTo(-lift, 0);+ expect(+ await page.evaluate(+ () =>+ (+ navigator as unknown as {+ virtualKeyboard: {overlaysContent: boolean};+ }+ ).virtualKeyboard.overlaysContent,+ ),+ ).toBe(false);+ });++ test('the dock rides down on Gboard’s slide from the blur', async ({+ page,+ }) => {+ const {dock, editable} = await openChat(page, {android: true});+ await editable.focus();+ await reportAt(page, COVER);+ await waitForRest(dock);+ await page.waitForTimeout(100);+ const lifted = -(await dockY(dock));+ const blurAt = await editable.evaluate(el => {+ let at = 0;+ el.addEventListener(+ 'focusout',+ event => {+ at = event.timeStamp;+ },+ {once: true},+ );+ (el as HTMLElement).blur();+ return at;+ });+ await waitForAnimation(dock);+ const start = await dock.evaluate(el =>+ Math.max(+ ...el.getAnimations().map(a => Number(a.startTime ?? -Infinity)),+ ),+ );+ expect(+ Math.abs(start - (blurAt + ANDROID_KEYBOARD.hideAfterBlurMs)),+ ).toBeLessThan(8);+ const ride = rideOf(+ await holdAnimations(page, dock, {+ judges: {target: dock, property: 'translate'},+ }),+ );+ const samples = curveOf(+ await sampleCurve(dock, timeline(ride.offsetMs + ride.curveEndMs)),+ 'translateY',+ );+ await releaseAnimations(page);+ // The layout still holds the lift; the translate takes the dock down.+ const ease = cubicBezier(ANDROID_KEYBOARD.hideCurve);+ const result = compareCurve(+ samples,+ t =>+ lifted *+ ease(+ Math.min(+ 1,+ Math.max(0, (t - ride.offsetMs) / ANDROID_KEYBOARD.hideMs),+ ),+ ),+ 0.5,+ );+ expect(result.maxError, JSON.stringify(result.worst)).toBeLessThanOrEqual(+ 0.5,+ );+ expect(ride.curveEndMs).toBeCloseTo(ANDROID_KEYBOARD.hideMs, -1);+ });++ test('Reduce Motion: the dock never travels with Gboard (design:reduced-motion)', async ({+ page,+ }) => {+ await page.emulateMedia({reducedMotion: 'reduce'});+ const {dock, editable, lift} = await openChat(page, {android: true});+ await editable.focus();+ const ys = await editable.evaluate(async (el, cover) => {+ let host: HTMLElement | null = el as HTMLElement;+ while (host != null && getComputedStyle(host).position !== 'sticky') {+ host = host.parentElement;+ }+ const read = () => {+ const style = getComputedStyle(host as HTMLElement);+ const value = style.translate;+ const translate =+ value === 'none' ? 0 : parseFloat(value.split(' ')[1] ?? '0');+ return translate - (parseFloat(style.bottom) || 0);+ };+ const out: number[] = [];+ const until = performance.now() + 900;+ const sample = () => {+ out.push(read());+ if (performance.now() < until) {+ requestAnimationFrame(sample);+ }+ };+ requestAnimationFrame(sample);+ (window as unknown as {__keyboard: (c: number) => void}).__keyboard(+ cover,+ );+ await new Promise(resolve => setTimeout(resolve, 900));+ return out;+ }, COVER);+ for (const y of ys) {+ expect(+ Math.abs(y) < 0.5 || Math.abs(y + lift) < 0.5,+ JSON.stringify(ys.map(Math.round)),+ ).toBe(true);+ }+ expect(ys.at(-1)).toBeCloseTo(-lift, 0);+ expect(await dock.evaluate(el => getComputedStyle(el).opacity)).toBe('1');+ });++ test('Reduce Motion: a hide Chrome reports in steps moves the dock once, after the keyboard has gone', async ({+ page,+ }) => {+ await page.emulateMedia({reducedMotion: 'reduce'});+ const {dock, editable, lift} = await openChat(page, {android: true});+ await editable.focus();+ await showKeyboard(page);+ // The layout has taken the keyboard's lift: the show is over.+ await expect+ .poll(async () =>+ dock.evaluate(el => parseFloat(getComputedStyle(el).bottom) || 0),+ )+ .toBeCloseTo(lift, 0);+ await expect.poll(async () => dockY(dock)).toBeCloseTo(-lift, 0);+ // Under Remove animations, Chrome reports Back's hide as lower keyboards+ // that are still up, then none. Each frame records where the dock is drawn+ // and the layout's offset.+ const frames = await dock.evaluate(async (el, cover) => {+ const out: {y: number; bottom: number}[] = [];+ const read = () => {+ const style = getComputedStyle(el);+ const translate =+ style.translate === 'none'+ ? 0+ : parseFloat(style.translate.split(' ')[1] ?? '0') || 0;+ const bottom = parseFloat(style.bottom) || 0;+ out.push({y: translate - bottom, bottom});+ };+ const until = performance.now() + 900;+ const sample = () => {+ read();+ if (performance.now() < until) {+ requestAnimationFrame(sample);+ }+ };+ requestAnimationFrame(sample);+ const keyboard = (window as unknown as {__keyboard: (c: number) => void})+ .__keyboard;+ for (const share of [0.6, 0.35, 0.15, 0]) {+ await new Promise(resolve => setTimeout(resolve, 40));+ keyboard(Math.round(cover * share));+ }+ await new Promise(resolve => setTimeout(resolve, 900));+ return out;+ }, COVER);+ const detail = JSON.stringify(+ frames.map(({y, bottom}) => [Math.round(y), Math.round(bottom)]),+ );+ // Every frame draws the dock where the keyboard's top was, or at rest.+ for (const {y} of frames) {+ expect(Math.abs(y + lift) < 0.5 || Math.abs(y) < 0.5, detail).toBe(true);+ }+ // The layout's offset changes once: from the lift to none.+ expect(+ [...new Set(frames.map(({bottom}) => Math.round(bottom)))],+ detail,+ ).toEqual([Math.round(lift), 0]);+ expect(frames.at(-1)?.y ?? Number.NaN, detail).toBeCloseTo(0, 0);+ });+});diff --git a/packages/core/src/Chat/keyboardSurface.ts b/packages/core/src/Chat/keyboardSurface.tsnew file mode 100644index 0000000000..f9244af13a--- /dev/null+++ b/packages/core/src/Chat/keyboardSurface.ts@@ -0,0 +1,39 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file keyboardSurface.ts+ * @input createSharedContext, the keyboard module's touch gate+ * (followsKeyboard)+ * @output Exports KeyboardSurfaceContext and focusInKeyboardSurface: whether a+ * composer sits in ChatLayout's composer region, and the focus it delivers+ * @position Internal to Chat: ChatLayout provides it; ChatComposer and+ * ChatComposerInput read it+ *+ * Under a finger in a top-level page, focus skips the browser's reveal, which+ * on iOS scrolls the whole page. Elsewhere the browser's own focus applies.+ *+ * SYNC: update ChatLayout.tsx, ChatComposer.tsx and ChatComposerInput.tsx+ */++import {followsKeyboard} from '../keyboard/keyboardTarget';+import {createSharedContext} from '../utils/sharedContext';++export const KeyboardSurfaceContext = createSharedContext(+ 'KeyboardSurfaceContext',+ 1,+ false,+);++/** Focuses `element` the way its surface wants (see the file header). */+export function focusInKeyboardSurface(+ element: HTMLElement,+ isKeyboardSurface: boolean,+): void {+ if (isKeyboardSurface && followsKeyboard(element.ownerDocument.defaultView)) {+ element.focus({preventScroll: true});+ } else {+ element.focus();+ }+}diff --git a/packages/core/src/Chat/useChatKeyboard.test.tsx b/packages/core/src/Chat/useChatKeyboard.test.tsxnew file mode 100644index 0000000000..c97ec8e1bd--- /dev/null+++ b/packages/core/src/Chat/useChatKeyboard.test.tsx@@ -0,0 +1,859 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file useChatKeyboard.test.tsx+ * @input vitest, Testing Library, ChatLayout, a stand-in visual viewport+ * @output Tests ChatLayout's keyboard behavior in jsdom. It covers the dock's+ * lift, the message area's room and the dock's ride down at a blur. It+ * also covers the touches the composer claims, focus moves and Done's park+ * on the composer group+ * @position Unit tests for Chat/useChatKeyboard.ts; the browser spec proves+ * Chrome's ride+ */++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import {act, fireEvent, render, screen} from '@testing-library/react';+import {ChatComposer} from './ChatComposer';+import {ChatLayout} from './ChatLayout';+import {editableToClaim} from './useChatKeyboard';+import {getKeyboardLayoutGuide} from '../keyboard/keyboardLayoutGuide';+import {__resetInteractionModalityForTest} from '../utils/interactionModality';+import {__focusTakeoverCallersForTest} from '../keyboard/keyboardHeight';++// jsdom dates events on the epoch clock, but a browser dates them on+// performance.now()'s, which the keyboard guide reads them against.+let eventTime: {mockRestore: () => void} | null = null;++beforeEach(() => {+ eventTime = vi+ .spyOn(Event.prototype, 'timeStamp', 'get')+ .mockImplementation(() => performance.now());+});++afterEach(() => {+ eventTime?.mockRestore();+ eventTime = null;+});++type FakeViewport = EventTarget & {+ height: number;+ offsetTop: number;+ scale: number;+ width?: number;+};++let viewport: FakeViewport;++function report(height: number) {+ viewport.height = height;+ act(() => {+ viewport.dispatchEvent(new Event('resize'));+ });+}++function dockOf(container: HTMLElement): HTMLElement {+ return container.querySelector<HTMLElement>('[data-testid="composer"]')!+ .parentElement!.parentElement!.parentElement!;+}++function messagesOf(): HTMLElement {+ return screen.getByTestId('layout').firstElementChild as HTMLElement;+}++// The room the message area's end padding makes for the keyboard, CSS px: the+// `+ Npx` its functional style adds to the density's own padding.+function keyboardRoom(element: HTMLElement): number {+ const match = /--[\w-]+:\s*calc\([^;]*\+\s*(-?[\d.]+)px\)/.exec(+ element.getAttribute('style') ?? '',+ );+ return match == null ? 0 : Number(match[1]);+}++// The lift an element is laid out with: the value its functional style+// (a StyleX dynamic style, an inline custom property) carries, CSS px.+function layoutLift(element: HTMLElement): number {+ const match = /--[\w-]+:\s*(-?[\d.]+)px/.exec(+ element.getAttribute('style') ?? '',+ );+ return match == null ? 0 : Number(match[1]);+}++// Lets the ride end (the animator's clock) and its end reach the layout.+async function settle() {+ await act(async () => {+ const sleep = async (ms: number) =>+ new Promise(resolve => setTimeout(resolve, ms));+ // The guide publishes a report's transition within a few frames, then+ // checks it a while after its curve ends: the ride is over by then.+ await sleep(200);+ const {start, curve} = getKeyboardLayoutGuide(window).transition;+ const checked = start + (curve?.durationMs ?? 0) + 200;+ await vi.waitFor(+ () => {+ if (document.getAnimations?.().some(a => a.playState === 'running')) {+ throw new Error('still riding');+ }+ if (performance.now() < checked) {+ throw new Error('still riding');+ }+ },+ {timeout: 3000, interval: 20},+ );+ await sleep(50);+ });+}++function renderLayout() {+ const result = render(+ <ChatLayout+ data-testid="layout"+ composer={+ <div data-testid="composer">+ <textarea aria-label="Message" />+ </div>+ }>+ <p>Hello</p>+ </ChatLayout>,+ );+ // jsdom has no layout: the root fills the viewport, as a full-page chat does.+ screen.getByTestId('layout').getBoundingClientRect = () =>+ new DOMRect(0, 0, window.innerWidth, window.innerHeight);+ return result;+}++describe('ChatLayout and the software keyboard', () => {+ // A phone: its primary pointer is a coarse finger.+ const stubPointer = (pointer: 'coarse' | 'fine') => {+ vi.stubGlobal('matchMedia', (query: string) => ({+ matches: query === `(pointer: ${pointer})`,+ media: query,+ addEventListener: () => {},+ removeEventListener: () => {},+ }));+ };++ beforeEach(() => {+ stubPointer('coarse');+ viewport = Object.assign(new EventTarget(), {+ height: window.innerHeight,+ offsetTop: 0,+ scale: 1,+ });+ Object.defineProperty(window, 'visualViewport', {+ configurable: true,+ value: viewport,+ });+ });++ afterEach(() => {+ Reflect.deleteProperty(window, 'visualViewport');+ Reflect.deleteProperty(navigator, 'virtualKeyboard');+ vi.unstubAllGlobals();+ });++ // Chrome on Android: the guide publishes Gboard's slides where the+ // browser has the VirtualKeyboard API.+ const stubChromeKeyboard = () => {+ Object.defineProperty(navigator, 'virtualKeyboard', {+ configurable: true,+ value: {overlaysContent: false},+ });+ };++ it('rides nothing without the VirtualKeyboard API, as in Safari on iOS: the layout follows the height alone', async () => {+ const guide = getKeyboardLayoutGuide(window);+ const subscribe = vi.spyOn(guide, 'subscribe');+ const {container} = renderLayout();+ report(window.innerHeight - 300);+ expect(dockOf(container).style.translate).toBe('');+ await settle();+ expect(layoutLift(dockOf(container))).toBe(300);+ expect(subscribe).not.toHaveBeenCalled();+ subscribe.mockRestore();+ });++ it('attaches nothing of the ride under a fine pointer: the layout follows the height alone', async () => {+ stubPointer('fine');+ const guide = getKeyboardLayoutGuide(window);+ const subscribe = vi.spyOn(guide, 'subscribe');+ const {container} = renderLayout();+ report(window.innerHeight - 300);+ await settle();+ expect(layoutLift(dockOf(container))).toBe(300);+ expect(dockOf(container).style.translate).toBe('');+ // Nothing subscribed the keyboard layout guide.+ expect(subscribe).not.toHaveBeenCalled();+ subscribe.mockRestore();+ });++ it('lays the dock and the room after the messages out from the keyboard height', async () => {+ const {container} = renderLayout();+ report(window.innerHeight - 300);+ await settle();+ // The layout is right with no animation running. The ride's translate is+ // handed back to it: back at identity, the animator takes it off.+ expect(layoutLift(dockOf(container))).toBe(300);+ expect(keyboardRoom(messagesOf())).toBe(300);+ expect(dockOf(container).style.translate).toBe('');+ });++ it('adds no element for the keyboard: the root holds the message area and the dock', async () => {+ renderLayout();+ report(window.innerHeight - 300);+ await settle();+ // The room is the message area's end padding, not an element of its own.+ expect(screen.getByTestId('layout').children).toHaveLength(2);+ });++ it('keeps a transcript at its newest message there', async () => {+ renderLayout();+ // Past the mount's own first-frame scroll to the end.+ await settle();+ const root = screen.getByTestId('layout');+ let scrollTop = 1000 - 600;+ Object.defineProperties(root, {+ clientHeight: {configurable: true, get: () => 600},+ scrollHeight: {+ configurable: true,+ get: () => 1000 + keyboardRoom(messagesOf()),+ },+ scrollTop: {+ configurable: true,+ get: () => scrollTop,+ set: (value: number) => {+ scrollTop = value;+ },+ },+ });+ report(window.innerHeight - 300);+ await settle();+ expect(scrollTop).toBe(1300 - 600);+ });++ // A transcript of 1,000 px in a 600 px root, plus the keyboard's room, that+ // the reader scrolls to `top`. The stream scroll hears each scroll.+ function scrolledTranscript(top: number) {+ const root = screen.getByTestId('layout');+ let scrollTop = 1000 - 600;+ Object.defineProperties(root, {+ clientHeight: {configurable: true, get: () => 600},+ offsetHeight: {configurable: true, get: () => 600},+ scrollHeight: {+ configurable: true,+ get: () => 1000 + keyboardRoom(messagesOf()),+ },+ scrollTop: {+ configurable: true,+ get: () => scrollTop,+ set: (value: number) => {+ scrollTop = value;+ },+ },+ });+ // From the end, up to `top`, as a reader scrolls.+ act(() => {+ root.dispatchEvent(new Event('scroll'));+ });+ scrollTop = top;+ act(() => {+ root.dispatchEvent(new Event('scroll'));+ });+ act(() => {+ root.dispatchEvent(new Event('scrollend'));+ });+ return {+ get scrollTop() {+ return scrollTop;+ },+ };+ }++ it('leaves a transcript the reader scrolled up where it is', async () => {+ renderLayout();+ // Past the mount's own first-frame scroll to the end.+ await settle();+ const transcript = scrolledTranscript(100);+ report(window.innerHeight - 300);+ await settle();+ expect(transcript.scrollTop).toBe(100);+ });++ it('keeps a reader the stream scroll still follows, 5 px above the end, at the newest message', async () => {+ renderLayout();+ await settle();+ // Within the stream scroll's lock distance, so it still follows.+ const transcript = scrolledTranscript(1000 - 600 - 5);+ report(window.innerHeight - 300);+ await settle();+ expect(transcript.scrollTop).toBe(1300 - 600);+ });++ it('rides the dock down from the blur, ahead of the layout, which follows the keyboard', async () => {+ stubChromeKeyboard();+ const {container} = renderLayout();+ const field = screen.getByRole('textbox', {name: 'Message'});+ act(() => field.focus());+ report(window.innerHeight - 300);+ await settle();+ act(() => field.blur());+ await settle();+ // The keyboard is still up (no report yet): the layout keeps its lift,+ // and the ride has taken the dock down on top of it.+ expect(layoutLift(dockOf(container))).toBe(300);+ expect(dockOf(container).style.translate).toBe('0px 300px');+ report(window.innerHeight);+ await settle();+ expect(layoutLift(dockOf(container))).toBe(0);+ expect(keyboardRoom(messagesOf())).toBe(0);+ expect(dockOf(container).style.translate).toBe('');+ });++ it('keeps the lift when the page is pinch-zoomed past 2x with the keyboard up', async () => {+ // WebKit reports innerWidth and innerHeight in the zoomed visual+ // viewport's px. At 2x, innerHeight alone reads no keyboard, and the dock+ // would drop under it.+ try {+ vi.stubGlobal('innerHeight', 714);+ vi.stubGlobal('innerWidth', 402);+ Object.assign(viewport, {width: 402});+ const {container} = renderLayout();+ screen.getByTestId('layout').getBoundingClientRect = () =>+ new DOMRect(0, 0, 402, 714);+ report(714 - 337);+ await settle();+ expect(layoutLift(dockOf(container))).toBe(337);++ vi.stubGlobal('innerHeight', 357);+ vi.stubGlobal('innerWidth', 201);+ Object.assign(viewport, {scale: 2, width: 201});+ report((714 - 337) / 2);+ await settle();+ expect(layoutLift(dockOf(container))).toBe(337);+ expect(keyboardRoom(messagesOf())).toBe(337);+ } finally {+ vi.unstubAllGlobals();+ }+ });++ it('moves nothing while no keyboard is up', async () => {+ const {container} = renderLayout();+ report(window.innerHeight);+ await settle();+ expect(dockOf(container).style.translate).toBe('');+ expect(layoutLift(dockOf(container))).toBe(0);+ expect(keyboardRoom(messagesOf())).toBe(0);+ });+});++describe('focus moves into the composer (spec:AST-099 FR4)', () => {+ // The primary pointer `matchMedia` reports: a touch screen's coarse finger,+ // or a desktop's fine mouse.+ function primaryPointer(pointer: 'coarse' | 'fine') {+ vi.stubGlobal('matchMedia', (query: string) => ({+ matches: query === `(pointer: ${pointer})`,+ media: query,+ addEventListener: () => {},+ removeEventListener: () => {},+ }));+ }++ function renderWithSearch(composerText: 'textarea' | 'contenteditable') {+ render(+ <>+ <input aria-label="Search" />+ <ChatLayout+ data-testid="layout"+ composer={+ composerText === 'textarea' ? (+ <textarea aria-label="Message" />+ ) : (+ <div+ aria-label="Message"+ contentEditable+ role="textbox"+ suppressContentEditableWarning+ />+ )+ }>+ <p>Hello</p>+ </ChatLayout>+ </>,+ );+ return {+ search: screen.getByRole('textbox', {name: 'Search'}),+ message: screen.getByRole('textbox', {name: 'Message'}),+ };+ }++ beforeEach(() => {+ Object.defineProperty(window, 'visualViewport', {+ configurable: true,+ value: Object.assign(new EventTarget(), {+ height: window.innerHeight,+ offsetTop: 0,+ scale: 1,+ }),+ });+ });++ afterEach(() => {+ Reflect.deleteProperty(window, 'visualViewport');+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ it('delivers a move from another field into the composer without the browser\u2019s reveal', () => {+ primaryPointer('coarse');+ const {search, message} = renderWithSearch('textarea');+ act(() => search.focus());+ const focus = vi.spyOn(message, 'focus');+ // The keyboard's next button, Tab, or a script moving focus.+ act(() => message.focus());+ expect(focus).toHaveBeenCalledWith({preventScroll: true});+ expect(document.activeElement).toBe(message);+ });++ it('delivers a move into contenteditable composer text the same way', () => {+ primaryPointer('coarse');+ const {search, message} = renderWithSearch('contenteditable');+ act(() => search.focus());+ const focus = vi.spyOn(message, 'focus');+ act(() => message.focus());+ expect(focus).toHaveBeenCalledWith({preventScroll: true});+ });++ it('leaves focus moves to the browser under a mouse', () => {+ primaryPointer('fine');+ const {search, message} = renderWithSearch('textarea');+ act(() => search.focus());+ const focus = vi.spyOn(message, 'focus');+ act(() => message.focus());+ expect(focus).not.toHaveBeenCalledWith({preventScroll: true});+ });++ it('moves focus to the composer group when the keyboard\u2019s Done ends entry', () => {+ primaryPointer('coarse');+ const {message} = renderWithSearch('textarea');+ const region = screen.getByRole('group');+ act(() => message.focus());+ const focus = vi.spyOn(region, 'focus');+ // Done blurs the composer's text, and focus goes to nothing.+ act(() => message.blur());+ expect(document.activeElement).toBe(region);+ expect(focus).toHaveBeenCalledWith({preventScroll: true});+ });++ it('shows the parked group\u2019s focus ring only after keyboard input (architecture:interaction-modality INV1)', () => {+ primaryPointer('coarse');+ __resetInteractionModalityForTest();+ const {message} = renderWithSearch('textarea');+ const region = screen.getByRole('group');+ // A tap on the text, then Done with nothing typed: no ring.+ fireEvent.pointerDown(message);+ act(() => message.focus());+ act(() => message.blur());+ expect(document.activeElement).toBe(region);+ expect(region.style.getPropertyValue('outline')).toBe('none');+ // The override leaves with the focus stop.+ act(() => message.focus());+ expect(region.style.getPropertyValue('outline')).toBe('');+ // Typed, then Done: the shared ring applies.+ fireEvent.keyDown(message, {key: 'a'});+ act(() => message.blur());+ expect(document.activeElement).toBe(region);+ expect(region.style.getPropertyValue('outline')).toBe('');+ __resetInteractionModalityForTest();+ });++ it('gives the composer group no name and no landmark, so two layouts on a page repeat none', () => {+ primaryPointer('coarse');+ render(+ <>+ <ChatLayout composer={<textarea aria-label="First" />}>+ <p>One</p>+ </ChatLayout>+ <ChatLayout composer={<textarea aria-label="Second" />}>+ <p>Two</p>+ </ChatLayout>+ </>,+ );+ expect(screen.queryAllByRole('region')).toHaveLength(0);+ // The layout names none of the caller's regions.+ const groups = screen.getAllByRole('group');+ expect(groups).toHaveLength(2);+ for (const group of groups) {+ expect(group.hasAttribute('aria-label')).toBe(false);+ expect(group.hasAttribute('aria-labelledby')).toBe(false);+ }+ });++ it('adds no tab stop for the composer region: it takes focus only for Done\u2019s park, and gives the focus stop up as focus leaves (spec:AST-017 FR59)', () => {+ primaryPointer('coarse');+ const {message} = renderWithSearch('textarea');+ const region = screen.getByRole('group');+ // No focus target until Done parks focus there, so a tap or a click+ // beside the composer never focuses the region.+ expect(region.hasAttribute('tabindex')).toBe(false);+ act(() => message.focus());+ act(() => message.blur());+ expect(document.activeElement).toBe(region);+ expect(region.tabIndex).toBe(-1);+ act(() => message.focus());+ expect(document.activeElement).toBe(message);+ expect(region.hasAttribute('tabindex')).toBe(false);+ });++ it('leaves the composer region a plain container under a mouse: no group, no name and no focus target (spec:AST-017 FR59)', () => {+ primaryPointer('fine');+ const {message} = renderWithSearch('textarea');+ expect(screen.queryByRole('group')).toBeNull();+ const layout = screen.getByTestId('layout');+ // The composer's containers inside the layout, the region among them.+ const containers = () => {+ const list: Element[] = [];+ for (+ let element = message.parentElement;+ element != null && element !== layout;+ element = element.parentElement+ ) {+ list.push(element);+ }+ return list;+ };+ expect(+ containers().filter(+ element =>+ element.hasAttribute('role') ||+ element.hasAttribute('aria-label') ||+ element.hasAttribute('tabindex'),+ ),+ ).toEqual([]);+ act(() => message.focus());+ act(() => message.blur());+ expect(+ containers().filter(element => element.hasAttribute('tabindex')),+ ).toEqual([]);+ });++ it('leaves focus where the browser puts it when it moves on to another field', () => {+ primaryPointer('coarse');+ const {search, message} = renderWithSearch('textarea');+ act(() => message.focus());+ act(() => search.focus());+ expect(document.activeElement).toBe(search);+ });++ it('leaves a blur to nothing to the browser under a mouse', () => {+ primaryPointer('fine');+ const {message} = renderWithSearch('textarea');+ act(() => message.focus());+ act(() => message.blur());+ expect(document.activeElement).toBe(document.body);+ });++ it('registers no touch listener and installs no focus takeover under a mouse (architecture INV13, spec:AST-094 FR24)', () => {+ primaryPointer('fine');+ const touchTargets: EventTarget[] = [];+ const addEventListener = EventTarget.prototype.addEventListener;+ vi.spyOn(EventTarget.prototype, 'addEventListener').mockImplementation(+ function (this: EventTarget, type, listener, options) {+ if (type.startsWith('touch')) {+ touchTargets.push(this);+ }+ addEventListener.call(this, type, listener, options);+ },+ );+ renderWithSearch('textarea');+ const layout = screen.getByTestId('layout');+ // React's own root listeners sit outside the layout.+ expect(+ touchTargets.filter(+ target => target instanceof Node && layout.contains(target),+ ),+ ).toEqual([]);+ expect(__focusTakeoverCallersForTest(document)).toBe(0);+ });++ it('installs the focus takeover for each ChatLayout under a finger, through the keyboard module\u2019s one listener (spec:AST-094 FR24)', () => {+ primaryPointer('coarse');+ render(+ <>+ <ChatLayout composer={<textarea aria-label="First" />}>+ <p>Hello</p>+ </ChatLayout>+ <ChatLayout composer={<textarea aria-label="Second" />}>+ <p>Hi</p>+ </ChatLayout>+ </>,+ );+ expect(__focusTakeoverCallersForTest(document)).toBe(2);+ });+});++describe('the taps the composer claims', () => {+ // jsdom has no isContentEditable: the nearest contenteditable decides.+ beforeEach(() => {+ Object.defineProperty(HTMLElement.prototype, 'isContentEditable', {+ configurable: true,+ get(this: HTMLElement) {+ const host = this.closest('[contenteditable]');+ return host != null && host.getAttribute('contenteditable') !== 'false';+ },+ });+ });++ afterEach(() => {+ Reflect.deleteProperty(HTMLElement.prototype, 'isContentEditable');+ document.body.innerHTML = '';+ });++ it('claims a touch on unfocused contenteditable text', () => {+ document.body.innerHTML =+ '<div contenteditable="true" id="editor"><p><span id="word">Hello</span></p></div>';+ expect(editableToClaim(document.getElementById('word'))).toBe(+ document.getElementById('editor'),+ );+ });++ it('leaves a control inside a token its own tap', () => {+ document.body.innerHTML =+ '<div contenteditable="true"><p>Hi <span contenteditable="false" data-astryx-token=""><button id="remove">×</button><span id="label">@Ada</span></span></p></div>';+ expect(editableToClaim(document.getElementById('remove'))).toBeNull();+ expect(editableToClaim(document.getElementById('label'))).toBeNull();+ });++ it('claims an unfocused text control too, whose own tap focus the browser would reveal (FR4)', () => {+ document.body.innerHTML =+ '<textarea id="draft">A long draft</textarea><input id="line" value="One line"><input id="box" type="checkbox"><textarea id="still" inputmode="none"></textarea>';+ const draft = document.getElementById('draft');+ expect(editableToClaim(draft)).toBe(draft);+ const line = document.getElementById('line');+ expect(editableToClaim(line)).toBe(line);+ // Nothing that brings up no keyboard.+ expect(editableToClaim(document.getElementById('box'))).toBeNull();+ expect(editableToClaim(document.getElementById('still'))).toBeNull();+ // A focused one keeps its own taps: the browser moves the caret.+ draft?.focus();+ expect(editableToClaim(draft)).toBeNull();+ });++ it('claims nothing that already has focus', () => {+ document.body.innerHTML =+ '<div contenteditable="true" id="editor"><p id="text">Hello</p></div>';+ document.getElementById('editor')!.focus();+ expect(editableToClaim(document.getElementById('text'))).toBeNull();+ });+});++describe('a text control composer tapped with nothing focused (spec:AST-099 FR4)', () => {+ beforeEach(() => {+ vi.stubGlobal('matchMedia', (query: string) => ({+ matches: query === '(pointer: coarse)',+ media: query,+ addEventListener: () => {},+ removeEventListener: () => {},+ }));+ Object.defineProperty(window, 'visualViewport', {+ configurable: true,+ value: Object.assign(new EventTarget(), {+ height: window.innerHeight,+ offsetTop: 0,+ scale: 1,+ }),+ });+ });++ afterEach(() => {+ Reflect.deleteProperty(window, 'visualViewport');+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ // A touch event as the browser raises it, at the given points.+ function touch(type: string, touches: {x: number; y: number}[]) {+ const event = new Event(type, {bubbles: true, cancelable: true});+ const list = touches.map((p, identifier) => ({+ identifier,+ clientX: p.x,+ clientY: p.y,+ }));+ Object.assign(event, {+ touches: type === 'touchend' ? [] : list,+ changedTouches: list,+ });+ return event;+ }++ it('is focused without the browser\u2019s reveal, as a contenteditable composer is', () => {+ render(+ <ChatLayout+ composer={+ <ChatComposer+ onSubmit={() => {}}+ input={<textarea aria-label="Message" />}+ />+ }>+ <p>Hello</p>+ </ChatLayout>,+ );+ const textarea = screen.getByRole('textbox', {name: 'Message'});+ expect(document.activeElement).not.toBe(textarea);+ const focus = vi.spyOn(textarea, 'focus');+ const end = touch('touchend', [{x: 10, y: 10}]);+ // The tap focuses the composer, which re-renders it.+ act(() => {+ textarea.dispatchEvent(touch('touchstart', [{x: 10, y: 10}]));+ textarea.dispatchEvent(end);+ });+ expect(end.defaultPrevented).toBe(true);+ expect(focus).toHaveBeenCalledWith({preventScroll: true});+ expect(document.activeElement).toBe(textarea);+ });++ it('raises the claimed tap\u2019s click once, so a caller\u2019s onClick still runs', () => {+ const onClick = vi.fn();+ render(+ <ChatLayout+ composer={+ <ChatComposer+ onSubmit={() => {}}+ input={<textarea aria-label="Message" onClick={onClick} />}+ />+ }>+ <p>Hello</p>+ </ChatLayout>,+ );+ const textarea = screen.getByRole('textbox', {name: 'Message'});+ // The route cancels the tap's touchend, so the browser raises no click.+ const end = touch('touchend', [{x: 10, y: 10}]);+ act(() => {+ textarea.dispatchEvent(touch('touchstart', [{x: 10, y: 10}]));+ textarea.dispatchEvent(end);+ });+ expect(end.defaultPrevented).toBe(true);+ expect(onClick).toHaveBeenCalledTimes(1);+ });+});++describe('inside an iframe (spec:AST-099 FR7)', () => {+ let frame: HTMLIFrameElement | null = null;++ afterEach(() => {+ frame?.remove();+ frame = null;+ vi.restoreAllMocks();+ vi.unstubAllGlobals();+ });++ // A touch event as the browser raises it, in the frame's own window.+ function touchEvent(+ win: Window & typeof globalThis,+ type: string,+ points: {x: number; y: number}[],+ changed = points,+ ) {+ const event = new win.Event(type, {bubbles: true, cancelable: true});+ const list = (ps: {x: number; y: number}[]) =>+ ps.map((p, identifier) => ({identifier, clientX: p.x, clientY: p.y}));+ Object.assign(event, {+ touches: list(points),+ changedTouches: list(changed),+ });+ return event;+ }++ it('leaves the composer\u2019s taps, focus and region to the browser, under a finger too', () => {+ frame = document.createElement('iframe');+ document.body.append(frame);+ const inner = frame.contentWindow as Window & typeof globalThis;+ // A touch screen: the top window has a coarse pointer too.+ vi.stubGlobal('matchMedia', (query: string) => ({+ matches: query === '(pointer: coarse)',+ media: query,+ addEventListener: () => {},+ removeEventListener: () => {},+ }));+ // A visual viewport, in a document that is not the top one; jsdom has no+ // isContentEditable, so the nearest contenteditable decides.+ Object.defineProperty(inner, 'matchMedia', {+ configurable: true,+ value: (query: string) => ({+ matches: query === '(pointer: coarse)',+ media: query,+ addEventListener: () => {},+ removeEventListener: () => {},+ }),+ });+ Object.defineProperty(inner, 'visualViewport', {+ configurable: true,+ value: Object.assign(new inner.EventTarget(), {+ height: inner.innerHeight,+ offsetTop: 0,+ scale: 1,+ }),+ });+ Object.defineProperty(inner.HTMLElement.prototype, 'isContentEditable', {+ configurable: true,+ get(this: HTMLElement) {+ const host = this.closest('[contenteditable]');+ return host != null && host.getAttribute('contenteditable') !== 'false';+ },+ });+ const host = inner.document.createElement('div');+ inner.document.body.append(host);+ render(+ <ChatLayout composer={<ChatComposer onSubmit={() => {}} />}>+ <p>Hello</p>+ </ChatLayout>,+ {container: host},+ );+ const editable = host.querySelector<HTMLElement>(+ '[contenteditable="true"]',+ )!;+ // The region is a plain container: Done parks nothing here.+ expect(host.querySelector('[role="group"]')).toBeNull();+ // A tap on the composer's text: the browser focuses it itself.+ editable.dispatchEvent(touchEvent(inner, 'touchstart', [{x: 10, y: 10}]));+ const end = touchEvent(inner, 'touchend', [], [{x: 10, y: 10}]);+ editable.dispatchEvent(end);+ expect(end.defaultPrevented).toBe(false);+ // The shell's empty-space tap focuses with the browser's reveal.+ const focus = vi.spyOn(editable, 'focus');+ fireEvent.click(editable.parentElement!);+ expect(focus).toHaveBeenCalled();+ expect(focus).not.toHaveBeenCalledWith({preventScroll: true});+ });+});++describe('the ChatLayout stories', () => {+ it('give a full-page layout the dynamic viewport\u2019s height, so the composer starts on screen', () => {+ // Where a phone browser's toolbar collapses, 100vh is the viewport with+ // the toolbar hidden: 859 px for 796 visible in Firefox for Android. That+ // puts the composer under the window's bottom edge.+ const here = path.dirname(fileURLToPath(import.meta.url));+ const stories = fs.readFileSync(+ path.join(+ here,+ '../../../../apps/storybook/stories/ChatLayout.stories.tsx',+ ),+ 'utf8',+ );+ // Storybook's preview pads every story by 16 px on each side.+ expect(stories).not.toMatch(/height: '100vh'/);+ expect(stories).not.toMatch(/height: '100dvh'/);+ expect(stories).toMatch(/height: 'calc\(100dvh - 32px\)'/);+ });+});++describe('what ChatLayout loads for the keyboard', () => {+ it('imports no gesture system: the composer tap is the keyboard module\u2019s focus route', () => {+ const here = path.dirname(fileURLToPath(import.meta.url));+ for (const file of ['ChatLayout.tsx', 'useChatKeyboard.ts']) {+ const source = fs.readFileSync(path.join(here, file), 'utf8');+ expect(source, file).not.toMatch(/from '\.\.\/gestures/);+ }+ });+});diff --git a/packages/core/src/Chat/useChatKeyboard.ts b/packages/core/src/Chat/useChatKeyboard.tsnew file mode 100644index 0000000000..3ee04a7637--- /dev/null+++ b/packages/core/src/Chat/useChatKeyboard.ts@@ -0,0 +1,497 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file useChatKeyboard.ts+ * @input React refs, the keyboard module's height, focus routes and layout+ * guide, the stream scroll's lock, the motion engine, the touch query and+ * layout viewport height+ * @output Exports useChatKeyboard: the lift for ChatLayout's dock and message+ * area, and the refs for its dock, message area and composer region+ * @position ChatLayout's keyboard behavior (Chat/ChatLayout.tsx); internal+ *+ * The composer sits on the keyboard, as in Messages on iOS. Where the layout+ * guide publishes the keyboard's slide, the dock rides it on the compositor.+ *+ * SYNC: update Chat/ChatLayout.tsx, ChatLayout.doc.mjs and keyboard/README.md+ */++import {useRef, useState, useSyncExternalStore, type RefObject} from 'react';+import {createMotionEngine, type Animator} from '../motion/animator';+import {+ claimTapFocus,+ findTextEntryControl,+ getKeyboardHeight,+ isTextEntryControl,+ refuseFocusReveal,+ subscribeKeyboardHeight,+} from '../keyboard/keyboardHeight';+import {+ getKeyboardLayoutGuide,+ keyboardProfileOf,+} from '../keyboard/keyboardLayoutGuide';+import {+ deliverTap,+ followsKeyboard,+ watchPans,+} from '../keyboard/keyboardTarget';+import type {KeyboardTransition} from '../keyboard/keyboardModel';+import {rideKeyboard} from '../keyboard/rideKeyboard';+import {layoutViewportHeight} from '../utils/layoutViewport';+import {useInteractionModalityTrackingFor} from '../utils/interactionModality';+import {isCoarsePointer} from '../utils/coarsePointer';+import {useTouchPresentation} from '../utils/touchPresentation';+import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';+import {+ isFollowingNewest,+ type UseChatStreamScrollReturn,+} from './useChatStreamScroll';++export interface UseChatKeyboardOptions {+ /** ChatLayout's root. */+ rootRef: RefObject<HTMLElement | null>;+ /** The element that scrolls the transcript (the root, or an outer one). */+ scrollRef: RefObject<HTMLElement | null>;+ /**+ * Whether the root scrolls itself (a sticky dock at its bottom) rather+ * than an outer scroller (a fixed dock at the layout viewport's bottom).+ */+ isSelfScrolling: boolean;+ /**+ * The stream scroll's jump to the newest message (useChatStreamScroll), the+ * owner of the transcript's lock.+ */+ scrollToBottom: UseChatStreamScrollReturn['scrollToBottom'];+}++export interface UseChatKeyboardResult {+ /**+ * The part of the keyboard over the dock, CSS px: the dock's offset from+ * its bottom and the room the message area's end padding adds.+ */+ lift: number;+ /** Callback ref for the dock container. */+ dockRef: (element: HTMLElement | null) => void;+ /** Callback ref for the message area. */+ messagesRef: (element: HTMLElement | null) => void;+ /**+ * Ref for the composer region. Its text taps are claimed, and Done parks+ * focus on it.+ */+ composerRef: RefObject<HTMLDivElement | null>;+}++// The lift the layout shows: a store the ride's end and keyboard reports+// write, and render reads.+function createLiftStore() {+ let value = 0;+ const listeners = new Set<() => void>();+ return {+ get: () => value,+ set: (next: number) => {+ if (next !== value) {+ value = next;+ for (const listener of listeners) {+ listener();+ }+ }+ },+ subscribe: (listener: () => void) => {+ listeners.add(listener);+ return () => {+ listeners.delete(listener);+ };+ },+ };+}++// Controls inside the composer's text (a token's button or link, an island+// that is not editable) keep their own taps, as ChatComposer's click-to-focus+// leaves them.+const OWN_TAPS =+ '[contenteditable="false"], button, a, [role="button"], [data-astryx-token]';++/**+ * The composer's text a touch landed in, when that tap would bring up the+ * keyboard and the text has no focus yet. It is contenteditable text, or a+ * text control passed as the composer's input. The browser would reveal+ * either by scrolling the page. Exported for its tests.+ */+export function editableToClaim(target: unknown): HTMLElement | null {+ let node = target as Node | null;+ if (node != null && node.nodeType !== 1) {+ node = node.parentNode;+ }+ const element = node as Element | null;+ if (element == null || typeof element.closest !== 'function') {+ return null;+ }+ const editable = isTextEntryControl(element)+ ? element+ : element.closest<HTMLElement>(+ '[contenteditable]:not([contenteditable="false"])',+ );+ if (editable == null || !isTextEntryControl(editable)) {+ return null;+ }+ const own = element.closest(OWN_TAPS);+ if (own != null && editable.contains(own)) {+ return null;+ }+ const active = editable.ownerDocument.activeElement;+ return active === editable || editable.contains(active) ? null : editable;+}++/**+ * Done's park: focus rests on the composer region. It is focusable for the+ * park alone, so a click or a tap beside the composer never focuses it. The+ * region gives the focus stop up as soon as focus leaves it. It shows the+ * focus ring only after keyboard input, as other script focus does.+ */+function parkFocus(region: HTMLElement, showsRing: boolean): void {+ region.setAttribute('tabindex', '-1');+ if (!showsRing) {+ region.style.setProperty('outline', 'none');+ }+ region.addEventListener(+ 'blur',+ () => {+ region.removeAttribute('tabindex');+ region.style.removeProperty('outline');+ },+ {once: true},+ );+ region.focus({preventScroll: true});+}++/**+ * Keeps ChatLayout's composer on top of the software keyboard.+ *+ * @example+ * ```+ * const keyboard = useChatKeyboard({rootRef, scrollRef, isSelfScrolling, scrollToBottom});+ * <div ref={keyboard.messagesRef} {...stylex.props(styles.messages(keyboard.lift))}>…</div>+ * <div ref={keyboard.dockRef} {...stylex.props(styles.dock(keyboard.lift))}>+ * <div ref={keyboard.composerRef}>…</div>+ * </div>+ * ```+ */+export function useChatKeyboard({+ rootRef,+ scrollRef,+ isSelfScrolling,+ scrollToBottom,+}: UseChatKeyboardOptions): UseChatKeyboardResult {+ const dock = useElementAnimator();+ const messages = useElementAnimator();+ const composerRef = useRef<HTMLDivElement>(null);+ // The lift the layout shows (read in render, so styles carry it) and its+ // mirror for the handlers below.+ const [liftStore] = useState(createLiftStore);+ const lift = useSyncExternalStore(+ liftStore.subscribe,+ liftStore.get,+ liftStore.get,+ );+ const liftRef = useRef(0);+ // Set while the guide's ride is under way: the layout waits for it. Each+ // ride's number, so only the latest one hands its translate back.+ const ridingRef = useRef(false);+ const rideRef = useRef(0);+ // Where the last ride took the dock's and the transcript's translates+ // (null: the transcript did not ride), until the layout takes them over.+ const dockTargetRef = useRef<number | null>(null);+ const messagesTargetRef = useRef<number | null>(null);+ // Whether the transcript followed its newest message, and where it was+ // scrolled, just before the layout's last change.+ const atEndRef = useRef(false);+ const scrollBeforeRef = useRef(0);+ const touchPresentation = useTouchPresentation();+ const readModality = useInteractionModalityTrackingFor(composerRef);++ const isTouch = touchPresentation.isTouch;++ // Synchronizes the layout with the keyboard: it subscribes to the layout+ // guide's transitions for the ride, and takes the height a mount finds.+ useIsomorphicLayoutEffect(() => {+ const root = rootRef.current;+ const win = root?.ownerDocument.defaultView;+ if (root == null || win == null) {+ return undefined;+ }+ // A sticky dock rests at the root's bottom edge, which may sit above or+ // below the layout viewport's; a fixed dock rests at the viewport's.+ // While a keyboard is up the dock rises until it clears the keyboard's+ // cover; without one it rests where the layout puts it.+ const liftFor = (inset: number) => {+ if (inset <= 0) {+ return 0;+ }+ // In layout px, as the root's rect is, under a pinch zoom too.+ const viewportBottom = layoutViewportHeight(win);+ const bottom = isSelfScrolling+ ? root.getBoundingClientRect().bottom+ : viewportBottom;+ return Math.max(0, bottom - (viewportBottom - inset));+ };+ // The stream scroll's lock decides whether the transcript follows its+ // newest message, as it does for new content. Its mark changes with the+ // lock, before any render.+ const isAtEnd = () => {+ const scroller = scrollRef.current;+ return scroller != null && isFollowingNewest(scroller);+ };+ // The layout takes the keyboard height's lift once no ride is under way.+ const commit = () => {+ if (ridingRef.current) {+ return;+ }+ const next = liftFor(getKeyboardHeight(win));+ if (Math.abs(next - liftRef.current) < 0.5) {+ return;+ }+ atEndRef.current = isAtEnd();+ scrollBeforeRef.current = scrollRef.current?.scrollTop ?? 0;+ liftStore.set(next);+ };++ // The ride plays the curve the guide publishes with each transition: the+ // keyboard's own motion. These are values, not motion roles, since the+ // system moves the keyboard on them whatever the page does.+ const follow = (transition: KeyboardTransition) => {+ // The ride: the dock goes where the guide says the keyboard will be,+ // from the keyboard's start, relative to the layout it rests in now.+ const target = liftRef.current - liftFor(transition.to);+ const atEnd = isAtEnd();+ dockTargetRef.current = target;+ messagesTargetRef.current = atEnd ? target : null;+ if (!transition.animated) {+ rideRef.current += 1;+ ridingRef.current = false;+ dock.animator.set({y: target});+ if (atEnd) {+ messages.animator.set({y: target});+ }+ commit();+ return;+ }+ // Under Reduce Motion the animator's default applies: no travel, a+ // cross-fade on a touch screen.+ const shown = {y: target};+ ridingRef.current = true;+ rideRef.current += 1;+ const ride = rideRef.current;+ // On the keyboard's own motion: Gboard's slide.+ const rides = [+ rideKeyboard(dock.animator, shown, transition)?.finished ??+ Promise.resolve(true),+ ];+ if (atEnd) {+ rides.push(+ rideKeyboard(messages.animator, shown, transition)?.finished ??+ Promise.resolve(true),+ );+ }+ void Promise.all(rides)+ .then(async done => {+ // A newer ride took over: it commits when it ends.+ if (!done.every(Boolean) || ride !== rideRef.current) {+ return;+ }+ // Hand back only once the presented animations are over too. So a+ // paused animation, as an inspector holds, is never left on top of+ // the new layout.+ const element = dock.animator.element;+ await Promise.all(+ (element?.getAnimations?.() ?? []).map(async animation =>+ animation.finished.catch(() => undefined),+ ),+ );+ if (ride === rideRef.current) {+ ridingRef.current = false;+ commit();+ }+ })+ .catch(() => undefined);+ };+ // The ride attaches only under a coarse primary pointer, where the guide+ // publishes the keyboard's own slide: Gboard's, in Chrome on Android.+ // Elsewhere the layout follows the height alone.+ const unsubscribe =+ isTouch && keyboardProfileOf(win) === 'chromium'+ ? getKeyboardLayoutGuide(win).subscribe(follow)+ : undefined;+ // A height change the guide has no ride for, as for a resize or a+ // rotation, takes its lift at once. This listener comes after the guide's,+ // so a ride claims the change first.+ let reportedHeight = getKeyboardHeight(win);+ const unsubscribeHeight = subscribeKeyboardHeight(win, event => {+ if (event.type === 'viewport' && event.height !== reportedHeight) {+ reportedHeight = event.height;+ commit();+ }+ });+ // Mounted under a keyboard that is already up: take its place at once.+ commit();+ return () => {+ unsubscribeHeight();+ unsubscribe?.();+ ridingRef.current = false;+ };+ }, [+ rootRef,+ scrollRef,+ isSelfScrolling,+ isTouch,+ dock.animator,+ messages.animator,+ liftStore,+ ]);++ // Synchronizes the dock's and the transcript's translates, and the+ // transcript's scroll, with the lift the layout just took. The translates+ // take the difference, so nothing moves on screen. The newest message stays+ // in view.+ useIsomorphicLayoutEffect(() => {+ const moved = lift - liftRef.current;+ if (Math.abs(moved) < 0.5) {+ return;+ }+ liftRef.current = lift;+ const dockTarget = dockTargetRef.current;+ const messagesTarget = messagesTargetRef.current;+ dockTargetRef.current = null;+ messagesTargetRef.current = null;+ // A ride that ended hands its translate (its target) to the layout; a+ // change no ride covered (a resize) is the layout's alone.+ if (dockTarget != null) {+ dock.animator.set({y: dockTarget + moved});+ }+ const scroller = scrollRef.current;+ if (scroller == null) {+ return;+ }+ // WebKit counts a translated transcript in the scroller's range. So the+ // ride's translate goes before the scroll is set. Otherwise the scroll+ // can stop past the content's end, and the sticky dock rises to meet it.+ if (messagesTarget != null) {+ messages.animator.set({y: 0});+ }+ if (atEndRef.current) {+ scrollToBottom({behavior: 'instant'});+ }+ // The padding's change may have clamped the scroll already: measure from+ // where it was before the layout changed.+ const shifted = scroller.scrollTop - scrollBeforeRef.current;+ if (messagesTarget != null && Math.abs(messagesTarget + shifted) >= 0.5) {+ messages.animator.set({y: messagesTarget + shifted});+ }+ }, [lift, scrollRef, dock.animator, messages.animator, scrollToBottom]);++ // Synchronizes the keyboard module's tap route on the composer with the+ // touch presentation. A tap on the composer's text that would bring up the+ // keyboard takes that route. It focuses here without Safari's reveal,+ // with the caret where the finger lifted, and raises the tap's click once.+ // Under a fine primary pointer no touch listener is registered. Inside an+ // iframe nothing changes.+ useIsomorphicLayoutEffect(() => {+ const composer = composerRef.current;+ const win = composer?.ownerDocument.defaultView ?? null;+ if (+ !touchPresentation.isTouch ||+ composer == null ||+ !followsKeyboard(win)+ ) {+ return undefined;+ }+ return claimTapFocus(composer, {+ claim: editableToClaim,+ deliver: deliverTap,+ });+ }, [touchPresentation.isTouch]);++ // A browser that reveals the composer itself pans the visual viewport after+ // the keyboard's report, while the composer still rides up. Chrome 124 on+ // Android pans by the keyboard's whole height. The keyboard module's+ // reveal-pan watch puts the pan back, so the page does not move.+ // Synchronizes the keyboard module's reports, under a finger only.+ useIsomorphicLayoutEffect(() => {+ const composer = composerRef.current;+ const win = composer?.ownerDocument.defaultView ?? null;+ if (+ !touchPresentation.isTouch ||+ composer == null ||+ !followsKeyboard(win)+ ) {+ return undefined;+ }+ const pans = watchPans(win, focused => composer.contains(focused));+ const unsubscribe = subscribeKeyboardHeight(win, event => {+ if (event.type === 'viewport') {+ pans.report(event.height);+ }+ });+ return () => {+ unsubscribe();+ pans.stop();+ };+ }, [touchPresentation.isTouch]);++ // Synchronizes the keyboard module's focus takeover, and the region's group+ // role, with the touch presentation. Every other move into the composer's+ // text takes it, under a finger only and where the keyboard is measured. A+ // desktop browser keeps its own focus. The pointer is read again on every+ // blur, so a tablet that docks a mouse drops the takeover. When Done ends+ // entry, focus moves to the composer region, a group that is no tab stop.+ // The next tap or Tab then starts from the composer.+ useIsomorphicLayoutEffect(() => {+ const composer = composerRef.current;+ const win = composer?.ownerDocument.defaultView ?? null;+ if (+ !touchPresentation.isTouch ||+ composer == null ||+ !followsKeyboard(win)+ ) {+ return undefined;+ }+ // The region is a group only while it is the park's target. It has no+ // accessible name: the layout names none of the caller's regions.+ composer.setAttribute('role', 'group');+ const stopTakeover = refuseFocusReveal(composer.ownerDocument, {+ isActive: () => isCoarsePointer(win),+ claim: destination => findTextEntryControl(destination, composer),+ park: origin => {+ if (findTextEntryControl(origin, composer) != null) {+ parkFocus(composer, readModality() === 'keyboard');+ }+ },+ });+ return () => {+ stopTakeover();+ composer.removeAttribute('role');+ };+ }, [touchPresentation.isTouch, readModality]);++ return {+ lift,+ dockRef: dock.ref,+ messagesRef: messages.ref,+ composerRef,+ };+}++/** A compositor animator for one element, bound through a stable callback ref. */+function useElementAnimator(): {+ readonly ref: (element: HTMLElement | null) => void;+ readonly animator: Animator;+} {+ const [result] = useState(() => {+ const animator = createMotionEngine(null);+ return {+ animator,+ ref: (element: HTMLElement | null) => animator.attach(element),+ };+ });+ return result;+}diff --git a/packages/core/src/Chat/useChatStreamScroll.ts b/packages/core/src/Chat/useChatStreamScroll.tsindex 0184f04b8f..52ca376dfe 100644--- a/packages/core/src/Chat/useChatStreamScroll.ts+++ b/packages/core/src/Chat/useChatStreamScroll.ts@@ -129,6 +129,29 @@ export interface UseChatStreamScrollReturn {const SIXTY_FPS_MS = 1000 / 60;+// The scrollers whose hook follows the newest message now, kept in step with+// each hook's lock.+const following = new WeakSet<Element>();++/**+ * Whether the stream scroll on `scroller` follows its newest message now, as+ * its lock says. Internal to Chat.+ */+export function isFollowingNewest(scroller: Element): boolean {+ return following.has(scroller);+}++// The lock's marks on the scroller: anchoring off while the hook follows, and+// the state `isFollowingNewest` reads.+function markFollowing(el: Element, locked: boolean): void {+ setScrollAnchoringOff(el, locked);+ if (locked) {+ following.add(el);+ } else {+ following.delete(el);+ }+}+export function useChatStreamScroll({scrollRef,enabled = true,@@ -168,7 +191,7 @@ export function useChatStreamScroll({setIsLocked(locked);const el = scrollRef.current;if (el != null) {- setScrollAnchoringOff(el, locked);+ markFollowing(el, locked);}},[scrollRef],@@ -349,7 +372,7 @@ export function useChatStreamScroll({}lastScrollTopRef.current = el.scrollTop;- setScrollAnchoringOff(el, lockedRef.current);+ markFollowing(el, lockedRef.current);const onScroll = () => {const {scrollTop, scrollHeight, offsetHeight} = el;@@ -395,7 +418,7 @@ export function useChatStreamScroll({return () => {el.removeEventListener('scroll', onScroll);el.removeEventListener('scrollend', onScrollEnd);- setScrollAnchoringOff(el, false);+ markFollowing(el, false);};}, [scrollRef, enabled, lockThreshold, buttonThreshold, setLocked]);diff --git a/packages/core/src/keyboard/README.md b/packages/core/src/keyboard/README.mdindex 5487156da3..ee3b113789 100644--- a/packages/core/src/keyboard/README.md+++ b/packages/core/src/keyboard/README.md@@ -49,8 +49,13 @@ that times motion with it. Everything here is internal todefault, lets the click guard (utils/clickGuard.ts) take the mouse eventsSafari may still send, and lets `deliver` focus the field.`focusAtPoint(field, x, y)` focuses it with `preventScroll` and puts the- caret under the finger. A touch past 10 px is- the browser's to scroll.+ caret under the finger. `deliverTap` (`keyboardTarget.ts`) does that and+ raises the tap's click once, since the cancelled tap raises none; the+ module's targets and ChatLayout's composer deliver with it.+ `followsKeyboard(win)` (`keyboardTarget.ts`) is the gate for all of it: a+ top-level document whose visual viewport shrinks for the keyboard, under+ a coarse primary pointer. A touch past+ 10 px is the browser's to scroll.- **The browser's own reveal pan (FR4):** `watchRevealPan(window, {owns})`is the one building block every keyboard-aware surface uses for a browserthat pans the visual viewport to a focused field after the keyboard's@@ -64,7 +69,9 @@ that times motion with it. Everything here is internal to`touchstart` subscription on the window's input stream, which lives onlywhile a surface watches. BottomSheet's hook watches while its sheet is presentedunder a coarse primary pointer; under a fine one it registers no touch- listener.+ listener. `watchPans(win, owns)` (`keyboardTarget.ts`) runs that loop on+ each height the module reports: the keyboard targets and ChatLayout's+ composer watch with it.- **Keyboard targets (`keyboardTarget.ts`):** a target keeps the focused fieldinside it above the keyboard, and registers so a field inside moves nothingitself (`registerKeyboardTarget`, `isInsideKeyboardTarget`).@@ -239,6 +246,13 @@ keyboard module measures them from the visual viewport, as in every browserdated back `hideReportLagMs`, the lag measured on blurs. Chrome can reportBack later in the slide, so on Back the content starts down after thekeyboard does.+- Under Remove animations (`prefers-reduced-motion: reduce`), Chrome reports+ a hide in steps: lower keyboards that are still up, then none. There, the+ keyboard module holds such a step and keeps reporting the shown height. The+ report of none, a report back up, or 300 ms without a new height ends the+ hold, and it lasts 1 s at most. A pan reports the same height and leaves it+ as it is. So every reader lays out once, after the keyboard has gone, and its+ Reduce Motion cross-fade plays once.- When focus moves from one field to another through something that brings upno keyboard (a popover's container), Chrome reports the keyboard gone andback within about 50 ms. A hide reported while a field that gained focus lessdiff --git a/packages/core/src/keyboard/keyboardHeight.test.ts b/packages/core/src/keyboard/keyboardHeight.test.tsindex d621313f1f..45a69be6ec 100644--- a/packages/core/src/keyboard/keyboardHeight.test.ts+++ b/packages/core/src/keyboard/keyboardHeight.test.ts@@ -5,7 +5,8 @@* @input keyboardHeight.ts, the keyboard layout guide, a stand-in visual* viewport* @output Tests for the on-screen keyboard module: the height, where it- * measures, its one set of listeners and the focus refusal+ * measures, a hide reported in steps, its one set of listeners and the+ * focus refusal* @position Keyboard module tests*/@@ -339,6 +340,179 @@ describe('where the keyboard is measured (FR6, FR7)', () => {});});+describe('a hide Chrome reports in steps under Remove animations (FR8)', () => {+ // Each test's subscriptions end after it, also when an expectation fails.+ const stops: (() => void)[] = [];+ afterEach(() => {+ for (const stop of stops.splice(0)) {+ stop();+ }+ vi.useRealTimers();+ });+ // Android's Remove animations setting reads as prefers-reduced-motion.+ const reduceMotion = (reduce: boolean) =>+ vi.stubGlobal(+ 'matchMedia',+ (query: string) =>+ ({+ matches: reduce && query === '(prefers-reduced-motion: reduce)',+ media: query,+ }) as unknown as MediaQueryList,+ );+ const withVirtualKeyboard = () =>+ Object.defineProperty(window.navigator, 'virtualKeyboard', {+ configurable: true,+ value: {overlaysContent: false},+ });+ const heightsOf = (listener: ReturnType<typeof vi.fn>) =>+ listener.mock.calls.map(([event]) => (event as KeyboardHeightEvent).height);+ const keyboard = (height: number) =>+ report({height: window.innerHeight - height});++ it('reports the hide once, with the report of none, and keeps the shown height until then', () => {+ withVirtualKeyboard();+ reduceMotion(true);+ const listener = vi.fn();+ stops.push(subscribeKeyboardHeight(window, listener));+ keyboard(300);+ for (const step of [200, 120, 60]) {+ keyboard(step);+ expect(getKeyboardHeight(window)).toBe(300);+ }+ keyboard(0);+ expect(heightsOf(listener)).toEqual([300, 0]);+ expect(getKeyboardHeight(window)).toBe(0);+ });++ it('gives the keyboard layout guide one hide for the steps, and no change', () => {+ withVirtualKeyboard();+ reduceMotion(true);+ const kinds: string[] = [];+ stops.push(+ getKeyboardLayoutGuide(window).subscribe(transition => {+ kinds.push(transition.kind);+ }),+ );+ keyboard(300);+ for (const step of [200, 120, 60]) {+ keyboard(step);+ }+ keyboard(0);+ expect(kinds).toEqual(['show', 'hide']);+ });++ it('reports a lower keyboard that stays up after a quiet spell', () => {+ vi.useFakeTimers();+ withVirtualKeyboard();+ reduceMotion(true);+ const listener = vi.fn();+ stops.push(subscribeKeyboardHeight(window, listener));+ keyboard(300);+ keyboard(250);+ act(() => {+ vi.advanceTimersByTime(299);+ });+ expect(heightsOf(listener)).toEqual([300]);+ act(() => {+ vi.advanceTimersByTime(1);+ });+ expect(heightsOf(listener)).toEqual([300, 250]);+ });++ it('keeps a step waiting through a pan, which reports the same height', () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout', 'performance']});+ withVirtualKeyboard();+ reduceMotion(true);+ const listener = vi.fn();+ stops.push(subscribeKeyboardHeight(window, listener));+ keyboard(300);+ keyboard(250);+ for (const offsetTop of [20, 40, 60]) {+ act(() => {+ vi.advanceTimersByTime(90);+ });+ Object.assign(viewport, {offsetTop});+ act(() => {+ viewport.dispatchEvent(new Event('scroll'));+ });+ }+ act(() => {+ vi.advanceTimersByTime(30);+ });+ expect(heightsOf(listener)).toEqual([300, 250]);+ });++ it('waits 1 s at most in all, however long the steps go on', () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout', 'performance']});+ withVirtualKeyboard();+ reduceMotion(true);+ const listener = vi.fn();+ stops.push(subscribeKeyboardHeight(window, listener));+ keyboard(300);+ for (const step of [280, 260, 240, 220]) {+ keyboard(step);+ act(() => {+ vi.advanceTimersByTime(250);+ });+ }+ expect(heightsOf(listener)).toEqual([300, 220]);+ });++ it('reports a keyboard that comes back up at once', () => {+ withVirtualKeyboard();+ reduceMotion(true);+ const listener = vi.fn();+ stops.push(subscribeKeyboardHeight(window, listener));+ keyboard(300);+ keyboard(200);+ keyboard(300);+ expect(heightsOf(listener)).toEqual([300, 300]);+ });++ it('reports every report of a show at once', () => {+ withVirtualKeyboard();+ reduceMotion(true);+ const listener = vi.fn();+ stops.push(subscribeKeyboardHeight(window, listener));+ keyboard(44);+ keyboard(300);+ expect(heightsOf(listener)).toEqual([44, 300]);+ });++ it.each([+ ['without Remove animations', true, false],+ ['without the VirtualKeyboard API', false, true],+ ])('reports every step %s', (_, hasApi, reduce) => {+ if (hasApi) {+ withVirtualKeyboard();+ }+ reduceMotion(reduce);+ const listener = vi.fn();+ stops.push(subscribeKeyboardHeight(window, listener));+ keyboard(300);+ for (const step of [200, 120, 60]) {+ keyboard(step);+ }+ keyboard(0);+ expect(heightsOf(listener)).toEqual([300, 200, 120, 60, 0]);+ });++ it('stops waiting when the last reader leaves', () => {+ vi.useFakeTimers();+ withVirtualKeyboard();+ reduceMotion(true);+ const listener = vi.fn();+ const stop = subscribeKeyboardHeight(window, listener);+ keyboard(300);+ keyboard(200);+ stop();+ act(() => {+ vi.advanceTimersByTime(1000);+ });+ expect(heightsOf(listener)).toEqual([300]);+ });+});+describe('one set of listeners per window (FR1, INV11)', () => {it('shares the listeners among subscribers and removes them with the last', () => {const add = vi.spyOn(viewport, 'addEventListener');diff --git a/packages/core/src/keyboard/keyboardHeight.ts b/packages/core/src/keyboard/keyboardHeight.tsindex 3ae99dc0e2..d3add41236 100644--- a/packages/core/src/keyboard/keyboardHeight.ts+++ b/packages/core/src/keyboard/keyboardHeight.ts@@ -7,9 +7,9 @@* @input The visual viewport, the window's input stream (focus, blur,* resize, scroll and touch), and the layout viewport's height* @output The on-screen keyboard module: measureKeyboardHeight,- * isKeyboardMeasurable, subscribeKeyboardHeight, getKeyboardHeight,- * isTextEntryControl, findTextEntryControl, refuseFocusReveal and- * watchRevealPan+ * isKeyboardMeasurable, hasVirtualKeyboard, subscribeKeyboardHeight,+ * getKeyboardHeight, isTextEntryControl, findTextEntryControl,+ * refuseFocusReveal and watchRevealPan* @position Core's one source for the on-screen keyboard. It is internal to* core and never exported from the package.*@@ -17,6 +17,7 @@*/import {armClickGuard} from '../utils/clickGuard';+import {matchesMediaQuery} from '../utils/coarsePointer';import {subscribeInput} from '../utils/inputStream';import {isNode} from '../utils/nodeType';import {layoutViewportHeight} from '../utils/layoutViewport';@@ -25,6 +26,15 @@ import {caretAt} from '../utils/selectionLock';// A shortfall smaller than this is rounding, not a keyboard.export const KEYBOARD_EPSILON = 1;+// Android's Remove animations setting, which makes Chrome report a hide in+// steps.+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';+// How long a step of a hide waits for the next report. It is longer than+// Gboard's whole hide (hideMs).+const HIDE_STEP_WAIT_MS = 300;+// How long a hide's steps wait in all, from the first. A toolbar's moves+// while a lower keyboard stays up cannot hold the layout longer.+const HIDE_STEP_LIMIT_MS = 1000;const NON_TEXT_INPUT_TYPES = new Set(['button','checkbox',@@ -114,20 +124,74 @@ function storeOf(win: Window): KeyboardStore {return store;}+/**+ * Whether `win` has the VirtualKeyboard API, as Chrome on Android does. The+ * keyboard layout guide reads Chrome's profile there (keyboardProfileOf).+ */+export function hasVirtualKeyboard(win: Window): boolean {+ return 'virtualKeyboard' in win.navigator;+}++// Whether a report of `height` is one step of a hide. Under Remove+// animations, Chrome on Android reports a hide as several lower keyboards+// that are still up, before the report of none.+function isHideStep(win: Window, shown: number, height: number): boolean {+ return (+ height > KEYBOARD_EPSILON &&+ height < shown - KEYBOARD_EPSILON &&+ hasVirtualKeyboard(win) &&+ matchesMediaQuery(win, REDUCED_MOTION_QUERY)+ );+}+function attach(win: Window, store: KeyboardStore): () => void {const viewport = win.visualViewport;store.height = measureKeyboardHeight(win);- const onViewport = (event: Event) => {- store.height = measureKeyboardHeight(win);- const report: KeyboardHeightEvent = {- type: 'viewport',- height: store.height,- timeStamp: event.timeStamp,- };+ // Set while a step of a hide waits. The store keeps the height it reported,+ // so every reader lays out once, when the keyboard comes to rest.+ let stepTimer: ReturnType<typeof setTimeout> | null = null;+ let stepHeight = 0;+ let stepLimit = 0;+ const deliver = (height: number, timeStamp: number) => {+ store.height = height;+ const report: KeyboardHeightEvent = {type: 'viewport', height, timeStamp};for (const listener of [...store.listeners]) {listener(report);}};+ const onViewport = (event: Event) => {+ const height = measureKeyboardHeight(win);+ if (isHideStep(win, store.height, height)) {+ // A pan reports the same step again, and leaves the wait as it is.+ if (+ stepTimer != null &&+ Math.abs(height - stepHeight) < KEYBOARD_EPSILON+ ) {+ return;+ }+ const now = win.performance.now();+ if (stepTimer == null) {+ stepLimit = now + HIDE_STEP_LIMIT_MS;+ } else {+ clearTimeout(stepTimer);+ }+ stepHeight = height;+ // The report of none, a report back up, or a quiet spell ends the wait.+ stepTimer = setTimeout(+ () => {+ stepTimer = null;+ deliver(measureKeyboardHeight(win), win.performance.now());+ },+ Math.min(HIDE_STEP_WAIT_MS, stepLimit - now),+ );+ return;+ }+ if (stepTimer != null) {+ clearTimeout(stepTimer);+ stepTimer = null;+ }+ deliver(height, event.timeStamp);+ };viewport?.addEventListener('resize', onViewport);viewport?.addEventListener('scroll', onViewport);// Only the window's own resize reports: a window's own event has no node as@@ -138,6 +202,10 @@ function attach(win: Window, store: KeyboardStore): () => void {}});return () => {+ if (stepTimer != null) {+ clearTimeout(stepTimer);+ stepTimer = null;+ }viewport?.removeEventListener('resize', onViewport);viewport?.removeEventListener('scroll', onViewport);stopResize();diff --git a/packages/core/src/keyboard/keyboardLayoutGuide.ts b/packages/core/src/keyboard/keyboardLayoutGuide.tsindex af83cf609a..4c4d9362b3 100644--- a/packages/core/src/keyboard/keyboardLayoutGuide.ts+++ b/packages/core/src/keyboard/keyboardLayoutGuide.ts@@ -15,6 +15,7 @@import {getKeyboardHeight,+ hasVirtualKeyboard,isTextEntryControl,subscribeKeyboardHeight,type KeyboardHeightEvent,@@ -34,7 +35,7 @@ import {* measured timing.*/export function keyboardProfileOf(win: Window): KeyboardProfile | null {- return 'virtualKeyboard' in win.navigator ? 'chromium' : null;+ return hasVirtualKeyboard(win) ? 'chromium' : null;}/** A window's keyboard layout guide. */diff --git a/packages/core/src/keyboard/keyboardTarget.test.ts b/packages/core/src/keyboard/keyboardTarget.test.tsindex ac2992601a..84c92ff251 100644--- a/packages/core/src/keyboard/keyboardTarget.test.ts+++ b/packages/core/src/keyboard/keyboardTarget.test.ts@@ -18,6 +18,7 @@ import {coveredBy,dockedAncestor,followKeyboard,+ followsKeyboard,keepFieldAboveKeyboard,nearestScroller,registerKeyboardTarget,@@ -190,6 +191,20 @@ afterEach(() => {vi.restoreAllMocks();});+describe('followsKeyboard', () => {+ it('holds for a top-level document with a visual viewport under a coarse pointer, and nowhere else', () => {+ expect(followsKeyboard(window)).toBe(true);+ expect(followsKeyboard(null)).toBe(false);+ // A fine primary pointer: a desktop browser.+ isCoarse = false;+ expect(followsKeyboard(window)).toBe(false);+ isCoarse = true;+ // No visual viewport: nothing measures the keyboard.+ Reflect.deleteProperty(window, 'visualViewport');+ expect(followsKeyboard(window)).toBe(false);+ });+});+describe('where a field is', () => {it('finds its nearest scroller, or else the document', () => {const list = element('div', {top: 0, height: 400}, {overflowY: 'auto'});diff --git a/packages/core/src/keyboard/keyboardTarget.ts b/packages/core/src/keyboard/keyboardTarget.tsindex cc92a76bfd..4b5d41d1cf 100644--- a/packages/core/src/keyboard/keyboardTarget.ts+++ b/packages/core/src/keyboard/keyboardTarget.ts@@ -5,7 +5,8 @@* @input The keyboard module's reports and focus claim, the layout guide,* rideKeyboard and the shared animator* @output The keyboard targets: their registry, followKeyboard for a docked- * or scrolling target, and keepFieldAboveKeyboard, a covered field's path+ * or scrolling target, and keepFieldAboveKeyboard, a covered field's path.+ * Also followsKeyboard, the touch gate, and deliverTap, a tap's delivery* @position Keyboard module, internal to core. useMobileKeyboard calls it.** SYNC: When modified, update /packages/core/src/keyboard/README.md@@ -397,7 +398,7 @@ function reveal(// caller's `onClick` still runs once. The click is synthetic: its `isTrusted`// is false. Like a real tap's click in Chrome and Safari, it is a touch// `PointerEvent`, or a `MouseEvent` where no `PointerEvent` exists.-function deliverTap(+export function deliverTap(control: HTMLElement,x: number,y: number,@@ -429,11 +430,17 @@ function deliverTap(control.dispatchEvent(click);}-// Puts back a pan the browser makes on its own after a keyboard report. This-// happens, for example, after a focus no claim saw: a script's `focus()` while-// nothing has focus. The field sits in place already, so the pan only displaces-// the page.-function watchPans(win: Window, owns: (focused: Element) => boolean) {+/**+ * Puts back a pan the browser makes on its own after a keyboard report. This+ * happens, for example, after a focus no claim saw: a script's `focus()` while+ * nothing has focus. The field sits in place already, so the pan only displaces+ * the page. Feed `report` each keyboard height the module reports; `owns`+ * says whether a focused element is one this watch keeps in place.+ */+export function watchPans(+ win: Window,+ owns: (focused: Element) => boolean,+): {report(height: number): void; stop(): void} {const watch = watchRevealPan(win, {owns});let lastHeight = getKeyboardHeight(win);return {@@ -459,9 +466,12 @@ function focusedFieldIn(target: Element): HTMLElement | null {: null;}-// Whether this window keeps fields above a keyboard at all: a top-level-// document whose visual viewport shrinks for the keyboard, under a finger.-function followsKeyboard(win: Window | null): win is Window {+/**+ * Whether `win` keeps fields above a keyboard at all: a top-level document+ * whose visual viewport shrinks for the keyboard, under a coarse primary+ * pointer.+ */+export function followsKeyboard(win: Window | null): win is Window {return win != null && isKeyboardMeasurable(win) && isCoarsePointer(win);}