1 | import { FocusableElement, DOMAttributes, FocusableDOMProps, FocusableProps } from "@react-types/shared";
|
2 | import React, { ReactNode, RefObject, ReactElement } from "react";
|
3 | /**
|
4 | * A utility function that focuses an element while avoiding undesired side effects such
|
5 | * as page scrolling and screen reader issues with CSS transitions.
|
6 | */
|
7 | export function focusSafely(element: FocusableElement): void;
|
8 | export interface FocusScopeProps {
|
9 | /** The contents of the focus scope. */
|
10 | children: ReactNode;
|
11 | /**
|
12 | * Whether to contain focus inside the scope, so users cannot
|
13 | * move focus outside, for example in a modal dialog.
|
14 | */
|
15 | contain?: boolean;
|
16 | /**
|
17 | * Whether to restore focus back to the element that was focused
|
18 | * when the focus scope mounted, after the focus scope unmounts.
|
19 | */
|
20 | restoreFocus?: boolean;
|
21 | /** Whether to auto focus the first focusable element in the focus scope on mount. */
|
22 | autoFocus?: boolean;
|
23 | }
|
24 | export interface FocusManagerOptions {
|
25 | /** The element to start searching from. The currently focused element by default. */
|
26 | from?: Element;
|
27 | /** Whether to only include tabbable elements, or all focusable elements. */
|
28 | tabbable?: boolean;
|
29 | /** Whether focus should wrap around when it reaches the end of the scope. */
|
30 | wrap?: boolean;
|
31 | /** A callback that determines whether the given element is focused. */
|
32 | accept?: (node: Element) => boolean;
|
33 | }
|
34 | export interface FocusManager {
|
35 | /** Moves focus to the next focusable or tabbable element in the focus scope. */
|
36 | focusNext(opts?: FocusManagerOptions): FocusableElement;
|
37 | /** Moves focus to the previous focusable or tabbable element in the focus scope. */
|
38 | focusPrevious(opts?: FocusManagerOptions): FocusableElement;
|
39 | /** Moves focus to the first focusable or tabbable element in the focus scope. */
|
40 | focusFirst(opts?: FocusManagerOptions): FocusableElement;
|
41 | /** Moves focus to the last focusable or tabbable element in the focus scope. */
|
42 | focusLast(opts?: FocusManagerOptions): FocusableElement;
|
43 | }
|
44 | /**
|
45 | * A FocusScope manages focus for its descendants. It supports containing focus inside
|
46 | * the scope, restoring focus to the previously focused element on unmount, and auto
|
47 | * focusing children on mount. It also acts as a container for a programmatic focus
|
48 | * management interface that can be used to move focus forward and back in response
|
49 | * to user events.
|
50 | */
|
51 | export function FocusScope(props: FocusScopeProps): JSX.Element;
|
52 | /**
|
53 | * Returns a FocusManager interface for the parent FocusScope.
|
54 | * A FocusManager can be used to programmatically move focus within
|
55 | * a FocusScope, e.g. in response to user events like keyboard navigation.
|
56 | */
|
57 | export function useFocusManager(): FocusManager;
|
58 | /**
|
59 | * Create a [TreeWalker]{@link https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker}
|
60 | * that matches all focusable/tabbable elements.
|
61 | */
|
62 | export function getFocusableTreeWalker(root: Element, opts?: FocusManagerOptions, scope?: Element[]): TreeWalker;
|
63 | /**
|
64 | * Creates a FocusManager object that can be used to move focus within an element.
|
65 | */
|
66 | export function createFocusManager(ref: RefObject<Element>, defaultOptions?: FocusManagerOptions): FocusManager;
|
67 | export interface AriaFocusRingProps {
|
68 | /**
|
69 | * Whether to show the focus ring when something
|
70 | * inside the container element has focus (true), or
|
71 | * only if the container itself has focus (false).
|
72 | * @default 'false'
|
73 | */
|
74 | within?: boolean;
|
75 | /** Whether the element is a text input. */
|
76 | isTextInput?: boolean;
|
77 | /** Whether the element will be auto focused. */
|
78 | autoFocus?: boolean;
|
79 | }
|
80 | export interface FocusRingAria {
|
81 | /** Whether the element is currently focused. */
|
82 | isFocused: boolean;
|
83 | /** Whether keyboard focus should be visible. */
|
84 | isFocusVisible: boolean;
|
85 | /** Props to apply to the container element with the focus ring. */
|
86 | focusProps: DOMAttributes;
|
87 | }
|
88 | /**
|
89 | * Determines whether a focus ring should be shown to indicate keyboard focus.
|
90 | * Focus rings are visible only when the user is interacting with a keyboard,
|
91 | * not with a mouse, touch, or other input methods.
|
92 | */
|
93 | export function useFocusRing(props?: AriaFocusRingProps): FocusRingAria;
|
94 | export interface FocusRingProps {
|
95 | /** Child element to apply CSS classes to. */
|
96 | children: ReactElement;
|
97 | /** CSS class to apply when the element is focused. */
|
98 | focusClass?: string;
|
99 | /** CSS class to apply when the element has keyboard focus. */
|
100 | focusRingClass?: string;
|
101 | /**
|
102 | * Whether to show the focus ring when something
|
103 | * inside the container element has focus (true), or
|
104 | * only if the container itself has focus (false).
|
105 | * @default false
|
106 | */
|
107 | within?: boolean;
|
108 | /** Whether the element is a text input. */
|
109 | isTextInput?: boolean;
|
110 | /** Whether the element will be auto focused. */
|
111 | autoFocus?: boolean;
|
112 | }
|
113 | /**
|
114 | * A utility component that applies a CSS class when an element has keyboard focus.
|
115 | * Focus rings are visible only when the user is interacting with a keyboard,
|
116 | * not with a mouse, touch, or other input methods.
|
117 | */
|
118 | export function FocusRing(props: FocusRingProps): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
|
119 | export interface FocusableOptions extends FocusableProps, FocusableDOMProps {
|
120 | /** Whether focus should be disabled. */
|
121 | isDisabled?: boolean;
|
122 | }
|
123 | export interface FocusableProviderProps extends DOMAttributes {
|
124 | /** The child element to provide DOM props to. */
|
125 | children?: ReactNode;
|
126 | }
|
127 | export let FocusableProvider: React.ForwardRefExoticComponent<FocusableProviderProps & React.RefAttributes<FocusableElement>>;
|
128 | export interface FocusableAria {
|
129 | /** Props for the focusable element. */
|
130 | focusableProps: DOMAttributes;
|
131 | }
|
132 | /**
|
133 | * Used to make an element focusable and capable of auto focus.
|
134 | */
|
135 | export function useFocusable(props: FocusableOptions, domRef: RefObject<FocusableElement>): FocusableAria;
|
136 |
|
137 | //# sourceMappingURL=types.d.ts.map
|