Skip to content

Commit 2bbdd7e

Browse files
alpharius-ckclaude
andcommitted
Merge branch 'main' into feat/refactor-icon-button-component
Take main's shared keyboard focus ring (#5107): - drop src/utils/focusRing.ts and take main's FAB, Switch and Checkbox - drop IconButton's own focus state and ring view; the ring now comes from useFocusRing with 'within' on the clip view, so it surrounds the outline and the touchable no longer draws a second one - keep the theme props on IconButton's TouchableRipple and TextInput.Icon - regenerate snapshots, add IconButton focus ring wiring tests Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2 parents 5bcea1d + 0181d96 commit 2bbdd7e

51 files changed

Lines changed: 3082 additions & 2754 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/6.x/docs/guides/migration.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -361,6 +361,34 @@ App tests change with it: a display-only element is no longer found by a role it
361361

362362
In a disabled `TextInput`, every `TextInput.Icon` takes the disabled color, also over `iconColor` and the error color. One with a handler is a disabled `IconButton`, and an `opacity` in its `style` doesn't apply.
363363

364+
### Focus indicator
365+
366+
Interactive components now draw the Material Design 3 keyboard focus indicator: a 3dp ring in `theme.colors.secondary`, 2dp outside the component. On web it shows when an element gets focus from the keyboard (`:focus-visible`), and on Android when it gets focus from a hardware keyboard or D-pad. Clicking or touching an element shows no ring. iOS shows no ring.
367+
368+
`Snackbar` rings its action and close button in `theme.colors.inversePrimary`, the color of its action label, because `secondary` barely shows on its `inverseSurface` background. If a component's background is the ring color, such as an `Appbar` with a `secondary` background, the rings of the controls on it don't show: give those controls a `theme` with a contrasting `secondary`. An `Appbar` passes its own `theme` on to the `Appbar.Action`, `Appbar.BackAction` and `Appbar.Content` placed directly in it.
369+
370+
Components that fill a clipping container or touch their neighbours draw the ring 3dp inside their edge instead: `List.Item`, `List.Accordion`, `Checkbox.Item`, `RadioButton.Item`, `Menu.Item`, the `FAB.Menu` items, `Drawer.Item`, the `BottomNavigation` tabs, `DataTable.Row`, `DataTable.Cell`, `DataTable.Title` and `SegmentedButtons`. `Drawer.CollapsedItem` draws it around its icon and label, 2dp clear of the active indicator. `FAB` and `Switch` draw this ring instead of their own, and `Checkbox` keeps its circular ring around the state layer.
371+
372+
A `TouchableRipple`, and every component built on it, rings only while it can be pressed. A disabled one shows no ring. One with no touch handler and no `disabled` is the plain view described in [TouchableRipple without a press handler](#touchableripple-without-a-press-handler): it isn't a keyboard stop, so it never rings. This applies to `TouchableRipple` only: a `Switch` or `Drawer.CollapsedItem` without a handler is still a keyboard stop and rings.
373+
374+
An outward ring sits outside the component, so a scroll view or a container with `overflow: 'hidden'` clips it, and a neighbour that touches the component can cover it. Chips in a horizontal `ScrollView`, or a `TouchableRipple` that fills the width of a scroll view, show only part of the ring. Give the container 5dp of padding, or pass `focusRing="inward"` where the component takes it:
375+
376+
```tsx
377+
<ScrollView horizontal contentContainerStyle={{ padding: 5 }}>
378+
<Chip onPress={showMusic}>Music</Chip>
379+
</ScrollView>
380+
381+
<TouchableRipple focusRing="inward" onPress={openSettings}>
382+
<Text>Settings</Text>
383+
</TouchableRipple>
384+
```
385+
386+
`TouchableRipple` takes a new `focusRing` prop, and so do the components whose props include it, such as `IconButton`, `List.Item`, `DataTable.Row` and `DataTable.Cell`. It is `'outward'`, `'inward'` or `'none'`. `'none'` draws no ring, but on web it leaves the browser's own focus outline, so a component that draws its own indicator also needs `outline: 'none'` on web.
387+
388+
On web the ring comes from a stylesheet that Paper adds to the page, and on these elements it takes precedence over your own `:focus-visible` outline styles. There is no app-wide switch to turn the ring off. Its color follows `theme.colors.secondary`, from the theme or a component's `theme` prop.
389+
390+
On web, `Button`, `Card`, the `Chip` body, `FAB`, `FAB.Extended` and the `FAB.Menu` trigger and items draw the ring with the CSS `:has()` selector. A browser without it (Chrome before 105, Safari before 15.4, Firefox before 121) shows its own focus outline just inside their edge instead.
391+
364392
### Libraries built on Paper
365393

366394
Libraries built on Paper may not support 6.x yet. For example, `react-native-paper-dates` 0.24.1 still uses `HelperText`, the 5.x theme exports and `theme.roundness`, so its `DatePickerInput` crashes when it shows a validation error.
@@ -406,6 +434,8 @@ To keep the height of the content row when setting `height` in `style`, add the
406434
</Appbar.Header>
407435
```
408436

437+
In `medium` and `large` mode, `Appbar` now passes its `theme` to `Appbar.BackAction`, `Appbar.Action` and `Appbar.Content`, as the `small` and `center-aligned` modes already did. These children of a medium or large bar with its own `theme` now take their colors, the title's font and their focus rings from that theme, not from the app's. In 5.x, a dark-themed bar in a light app drew dark icons and a dark title on its dark background.
438+
409439
### Avatar
410440

411441
The `style` prop for `Avatar.Icon`, `Avatar.Image` and `Avatar.Text` no longer configures the background color. Use the `backgroundColor` prop instead. The text or icon color is still derived from the background color unless `color` is specified.
@@ -670,6 +700,8 @@ The close button (`onClose`) now fills the trailing 34dp column reserved for it,
670700
671701
`hitSlop` now works on web: the touchable renders an invisible target that extends past its bounds. An ancestor with `overflow: 'hidden'` or a scroll view clips it, as on Android.
672702
703+
`TouchableRipple` draws the keyboard focus ring and takes a new `focusRing` prop. See [Focus indicator](#focus-indicator).
704+
673705
### TextInput
674706
675707
The Paper 6.x `TextInput` is a complete rewrite with a new API. Import the component the same way, but note that the props and behavior have changed significantly.

‎src/components/Appbar/Appbar.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,12 +258,14 @@ const Appbar = ({
258258
{renderAppbarContent({
259259
children,
260260
isDark,
261+
theme,
261262
renderOnly: ['Appbar.BackAction'],
262263
mode,
263264
})}
264265
{renderAppbarContent({
265266
children: filterAppbarActions(children, true),
266267
isDark,
268+
theme,
267269
renderOnly: ['Appbar.Action'],
268270
mode,
269271
})}
@@ -272,6 +274,7 @@ const Appbar = ({
272274
{renderAppbarContent({
273275
children: filterAppbarActions(children),
274276
isDark,
277+
theme,
275278
renderExcept: [
276279
'Appbar',
277280
'Appbar.BackAction',
@@ -285,6 +288,7 @@ const Appbar = ({
285288
{renderAppbarContent({
286289
children,
287290
isDark,
291+
theme,
288292
renderOnly: ['Appbar.Content'],
289293
mode,
290294
})}

‎src/components/Appbar/AppbarAction.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@ const AppbarAction = ({
9494
disabled={disabled}
9595
aria-label={ariaLabel}
9696
animated
97+
theme={theme}
9798
ref={ref}
9899
{...rest}
99100
/>

‎src/components/Appbar/AppbarContent.tsx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import type {
1111
import { modeTextVariant } from './utils';
1212
import { useInternalTheme } from '../../core/theming';
1313
import type { ThemeProp } from '../../theme/types';
14+
import { mergeDataSetProps, useFocusRing } from '../../utils/useFocusRing';
1415
import Text from '../Typography/Text';
1516
import type { TextRef } from '../Typography/Text';
1617

@@ -101,6 +102,14 @@ const AppbarContent = ({
101102
const theme = useInternalTheme(themeOverrides);
102103
const { colors, fonts } = theme;
103104

105+
// With `onPress` the title is a button, so it gets the keyboard focus ring
106+
// (MD3: interactive elements in an app bar have focus rings). It is a plain
107+
// `Pressable`, so it calls the hook directly. Outward, the default.
108+
const { target: focusTarget, ring: focusRing } = useFocusRing(
109+
disabled || !onPress,
110+
colors.secondary
111+
);
112+
104113
const titleTextColor = titleColor ? titleColor : colors.onSurface;
105114

106115
const modeContainerStyles = {
@@ -153,6 +162,19 @@ const AppbarContent = ({
153162
onPress={onPress}
154163
disabled={disabled}
155164
{...contentWrapperProps}
165+
// Like Switch: a ripple drawable owns the focused state, so Android does
166+
// not add its grey default focus highlight on top of the ring.
167+
android_ripple={{ color: 'transparent' }}
168+
onFocus={(e) => {
169+
focusTarget.onFocus?.(e);
170+
rest.onFocus?.(e);
171+
}}
172+
onBlur={(e) => {
173+
focusTarget.onBlur?.();
174+
rest.onBlur?.(e);
175+
}}
176+
{...mergeDataSetProps(rest, focusRing.dataSetProps)}
177+
style={[...contentWrapperProps.style, ...focusRing.style]}
156178
>
157179
{content}
158180
</Pressable>

‎src/components/BottomNavigation/BottomNavigationBar.tsx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,8 @@ const Touchable = <Route extends BaseRoute>({
213213
borderless,
214214
centered,
215215
rippleColor,
216+
focusRing,
217+
theme,
216218
...rest
217219
}: TouchableProps<Route>) =>
218220
TouchableRipple.supported ? (
@@ -222,6 +224,8 @@ const Touchable = <Route extends BaseRoute>({
222224
borderless={borderless}
223225
centered={centered}
224226
rippleColor={rippleColor}
227+
focusRing={focusRing}
228+
theme={theme}
225229
style={style}
226230
>
227231
{children}
@@ -574,6 +578,11 @@ const BottomNavigationBar = <Route extends BaseRoute>({
574578
borderless: true,
575579
centered: true,
576580
rippleColor: 'transparent',
581+
// Tabs fill the bar edge to edge and the bar clips
582+
// (`overflow: 'hidden'`), so an outward ring would lose its top
583+
// and bottom and read as two vertical lines between tabs.
584+
focusRing: 'inward',
585+
theme,
577586
onPress: () => onTabPress(eventForIndex(index)),
578587
onLongPress: () => onTabLongPress?.(eventForIndex(index)),
579588
testID: getTestID({ route }),

‎src/components/Button/Button.tsx‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import { useReduceMotion } from '../../theme/accessibility/ReduceMotionContext';
3232
import { toSpringCurve } from '../../theme/tokens/sys/motion';
3333
import type { ThemeProp } from '../../theme/types';
3434
import hasTouchHandler from '../../utils/hasTouchHandler';
35+
import { useFocusRing } from '../../utils/useFocusRing';
3536
import ActivityIndicator from '../ActivityIndicator';
3637
import Icon from '../Icon';
3738
import type { IconSource } from '../Icon';
@@ -446,14 +447,18 @@ const Button = ({
446447
// The clip carries the same radius transition as the `Surface`, so the
447448
// ripple and the disabled overlay follow the morph.
448449
//
449-
// TODO: revisit the focus ring's placement once #5084 lands.
450-
// https://github.com/callstack/react-native-paper/pull/5084 adds MD3 keyboard
451-
// focus indicators to every `TouchableRipple` consumer, so Button gets one
452-
// with no code here. Deliberately not implemented locally: a second ring here
453-
// would double up with it. The catch is placement — that PR defaults to
454-
// `focusRing="outward"` and warns an outward ring is trimmed by "any clipping
455-
// ancestor sized to its content", which is exactly this view. Button will
456-
// likely need `focusRing="inward"`, or the ring on the outer view.
450+
// The keyboard focus ring goes on the clip (`scope: 'within'`, as on FAB),
451+
// not on the ripple that takes focus: the ripple sits inside the outline's
452+
// border, so a ring measured from it would lose the border width from its
453+
// 2dp gap, and overlap a thick outline. Neither this view nor the `Surface`
454+
// sets `overflow`, so nothing here trims it. Off whenever the button can't
455+
// be pressed, as on TouchableRipple.
456+
const { target: focusTarget, ring: focusRing } = useFocusRing(
457+
disabled || !hasPassedTouchHandler,
458+
theme.colors.secondary,
459+
'outward',
460+
'within'
461+
);
457462
const shapeTransitionStyle = {
458463
transitionProperty: 'borderRadius',
459464
transitionDuration: shapeTransitionDuration,
@@ -496,7 +501,10 @@ const Button = ({
496501
shapeTransitionTimingFunction={shapeTimingFunction}
497502
style={[styles.button, style]}
498503
>
499-
<Reanimated.View style={[styles.clip, outlineStyle, clipStyle]}>
504+
<Reanimated.View
505+
style={[styles.clip, outlineStyle, clipStyle, ...focusRing.style]}
506+
{...focusRing.dataSetProps}
507+
>
500508
{backgroundOpacity < 1 && (
501509
<Reanimated.View
502510
pointerEvents="none"
@@ -509,7 +517,10 @@ const Button = ({
509517
)}
510518
<AnimatedTouchableRipple
511519
borderless
512-
style={innerClipStyle}
520+
focusRing="none"
521+
onFocus={focusTarget.onFocus}
522+
onBlur={focusTarget.onBlur}
523+
style={[innerClipStyle, ...focusTarget.style]}
513524
background={background}
514525
rippleColor={rippleColor}
515526
onPress={onPress}

‎src/components/Card/Card.tsx‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import { getCardColors } from './utils';
1919
import { useInternalTheme } from '../../core/theming';
2020
import type { Elevation, ThemeProp } from '../../theme/types';
2121
import hasTouchHandler from '../../utils/hasTouchHandler';
22+
import { mergeDataSetProps, useFocusRing } from '../../utils/useFocusRing';
2223
import Surface from '../Surface';
2324
import type { SurfaceStyle } from '../Surface';
2425

@@ -165,7 +166,6 @@ const Card = ({
165166
...rest
166167
}: (OutlinedCardProps | ElevatedCardProps | ContainedCardProps) & Props) => {
167168
const theme = useInternalTheme(themeOverrides);
168-
169169
const isMode = React.useCallback(
170170
(modeToCompare: Mode) => {
171171
return cardMode === modeToCompare;
@@ -180,6 +180,20 @@ const Card = ({
180180
onPressOut,
181181
});
182182

183+
// The ring goes on the Surface, the card's visible box (`scope: 'within'`),
184+
// not on the `Pressable` that takes focus: the caller's `style` sizes and
185+
// pads the Surface, so a ring on the content-sized `Pressable` would stop
186+
// short of a taller card's edge or sit inside its padding.
187+
//
188+
// Off without a touch handler too: the `Pressable` unmounts then, and a
189+
// focused one sends no blur, so the ring would come back with the handler.
190+
const { target: focusTarget, ring: focusRing } = useFocusRing(
191+
disabled || !hasPassedTouchHandler,
192+
theme.colors.secondary,
193+
'outward',
194+
'within'
195+
);
196+
183197
const [pressed, setPressed] = React.useState(false);
184198
const elevation = isMode('elevated') ? (pressed ? 2 : cardElevation) : 0;
185199

@@ -237,11 +251,12 @@ const Card = ({
237251
ref={ref}
238252
borderRadius={borderRadius}
239253
backgroundColor={!isMode('elevated') ? backgroundColor : undefined}
240-
style={style}
254+
style={[style, ...focusRing.style]}
241255
theme={theme}
242256
elevation={elevation}
243257
testID={hasPassedTouchHandler ? undefined : testID}
244258
{...rest}
259+
{...mergeDataSetProps(rest, focusRing.dataSetProps)}
245260
>
246261
{isMode('outlined') && (
247262
<View
@@ -267,6 +282,12 @@ const Card = ({
267282
onPressIn={handlePressIn}
268283
onPressOut={handlePressOut}
269284
testID={testID}
285+
// Like Switch: a ripple drawable owns the focused state, so Android does
286+
// not add its grey default focus highlight on top of the ring.
287+
android_ripple={{ color: 'transparent' }}
288+
onFocus={focusTarget.onFocus}
289+
onBlur={focusTarget.onBlur}
290+
style={[{ borderRadius }, ...focusTarget.style]}
270291
>
271292
{content}
272293
</Pressable>

‎src/components/Checkbox/Checkbox.tsx‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@ import { useInternalTheme } from '../../core/theming';
3131
import { useReduceMotion } from '../../theme/accessibility/ReduceMotionContext';
3232
import { tokens } from '../../theme/tokens';
3333
import type { ThemeProp } from '../../theme/types';
34-
import { webNoOutline } from '../../utils/focusRing';
3534
import hasTouchHandler from '../../utils/hasTouchHandler';
3635
import { isKeyboardFocusEvent } from '../../utils/isKeyboardFocusEvent';
3736
import { useSpaceKeyPress } from '../../utils/useSpaceKeyPress';
@@ -500,6 +499,8 @@ const Checkbox = ({
500499
onBlur={handleBlur}
501500
{...interactionHandlers}
502501
borderless
502+
// Checkbox draws its own circular ring around the state layer.
503+
focusRing="none"
503504
// The platform press paints the wrong thing: it covers the whole 48dp
504505
// target instead of the 40dp state layer, tints with a neutral role,
505506
// and on web its hover overlay doubles up with the layer. Android also
@@ -581,6 +582,10 @@ const Checkbox = ({
581582
);
582583
};
583584

585+
// Web-only style; not in StyleSheet because `outline` is outside ViewStyle.
586+
// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
587+
const webNoOutline = { outline: 'none' } as unknown as ViewStyle;
588+
584589
const styles = StyleSheet.create({
585590
// A definite size keeps a stretching parent from widening the container and
586591
// moving the checkbox away from where it is laid out.

‎src/components/Checkbox/CheckboxItem.tsx‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ import Checkbox from './Checkbox';
1111
import { useInternalTheme } from '../../core/theming';
1212
import type { ThemeProp, TypescaleKey } from '../../theme/types';
1313
import { getStateLayer } from '../../theme/utils/state';
14+
import hasTouchHandler from '../../utils/hasTouchHandler';
15+
import { useFocusRing } from '../../utils/useFocusRing';
1416
import { useSpaceKeyPress } from '../../utils/useSpaceKeyPress';
1517
import TouchableRipple from '../TouchableRipple/TouchableRipple';
1618
import type { Props as TouchableRippleProps } from '../TouchableRipple/TouchableRipple';
@@ -160,16 +162,35 @@ const CheckboxItem = ({
160162
textAlign,
161163
};
162164

165+
// A full-width row: an outward ring would run into the rows around it. Inward,
166+
// the ring goes on a childless overlay painted last (`'descendant'`): drawn
167+
// on the row itself, it would sit under the content view, and a background
168+
// set through `style` would hide it. Off
169+
// whenever the row can't be pressed, as on TouchableRipple.
170+
const { target: focusTarget, ring: focusRing } = useFocusRing(
171+
disabled || !hasTouchHandler({ onPress, onLongPress }),
172+
theme.colors.secondary,
173+
'inward',
174+
'descendant'
175+
);
176+
163177
return (
164178
<TouchableRipple
165179
aria-label={ariaLabel}
180+
focusRing="none"
166181
role="checkbox"
167182
aria-checked={status === 'indeterminate' ? 'mixed' : status === 'checked'}
168183
aria-disabled={disabled}
169184
onPress={onPress}
170185
onLongPress={onLongPress}
171-
onBlur={handleSpaceKeyBlur}
186+
onFocus={focusTarget.onFocus}
187+
onBlur={(e) => {
188+
handleSpaceKeyBlur(e);
189+
focusTarget.onBlur?.();
190+
}}
172191
{...spaceKeyHandlers}
192+
{...focusTarget.dataSetProps}
193+
style={focusTarget.style}
173194
testID={testID}
174195
disabled={disabled}
175196
theme={theme}
@@ -191,6 +212,11 @@ const CheckboxItem = ({
191212
</Text>
192213
{!isLeading && checkbox}
193214
</View>
215+
<View
216+
pointerEvents="none"
217+
style={[StyleSheet.absoluteFill, ...focusRing.style]}
218+
{...focusRing.dataSetProps}
219+
/>
194220
</TouchableRipple>
195221
);
196222
};

0 commit comments

Comments
 (0)