1/**
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 *
4 * This source code is licensed under the MIT license found in the
5 * LICENSE file in the root directory of this source tree.
6 *
7 * @format
8 */
9
10import {NativeSyntheticEvent} from '../../Types/CoreEventTypes';
11
12/**
13 * @see https://reactnative.dev/docs/accessibility#accessibility-properties
14 */
15export interface AccessibilityProps
16  extends AccessibilityPropsAndroid,
17    AccessibilityPropsIOS {
18  /**
19   * When true, indicates that the view is an accessibility element.
20   * By default, all the touchable elements are accessible.
21   */
22  accessible?: boolean | undefined;
23
24  /**
25   * Provides an array of custom actions available for accessibility.
26   */
27  accessibilityActions?: ReadonlyArray<AccessibilityActionInfo> | undefined;
28
29  /**
30   * Overrides the text that's read by the screen reader when the user interacts with the element. By default, the
31   * label is constructed by traversing all the children and accumulating all the Text nodes separated by space.
32   */
33  accessibilityLabel?: string | undefined;
34
35  /**
36   * Alias for accessibilityLabel  https://reactnative.dev/docs/view#accessibilitylabel
37   * https://github.com/facebook/react-native/issues/34424
38   */
39  'aria-label'?: string | undefined;
40
41  /**
42   * Accessibility Role tells a person using either VoiceOver on iOS or TalkBack on Android the type of element that is focused on.
43   */
44  accessibilityRole?: AccessibilityRole | undefined;
45  /**
46   * Accessibility State tells a person using either VoiceOver on iOS or TalkBack on Android the state of the element currently focused on.
47   */
48  accessibilityState?: AccessibilityState | undefined;
49
50  /**
51   * alias for accessibilityState
52   *
53   * see https://reactnative.dev/docs/accessibility#accessibilitystate
54   */
55  'aria-busy'?: boolean | undefined;
56  'aria-checked'?: boolean | 'mixed' | undefined;
57  'aria-disabled'?: boolean | undefined;
58  'aria-expanded'?: boolean | undefined;
59  'aria-selected'?: boolean | undefined;
60
61  /**
62   * Represents the nativeID of the associated label text. When the assistive technology focuses on the component with this props, the text is read aloud.
63   *
64   * @platform android
65   */
66  'aria-labelledby'?: string | undefined;
67
68  /**
69   * An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not obvious from the accessibility label.
70   */
71  accessibilityHint?: string | undefined;
72  /**
73   * Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars,
74   * it contains range information (minimum, current, and maximum).
75   */
76  accessibilityValue?: AccessibilityValue | undefined;
77
78  'aria-valuemax'?: AccessibilityValue['max'];
79  'aria-valuemin'?: AccessibilityValue['min'];
80  'aria-valuenow'?: AccessibilityValue['now'];
81  'aria-valuetext'?: AccessibilityValue['text'];
82  /**
83   * When `accessible` is true, the system will try to invoke this function when the user performs an accessibility custom action.
84   */
85  onAccessibilityAction?:
86    | ((event: AccessibilityActionEvent) => void)
87    | undefined;
88
89  /**
90   * [Android] Controlling if a view fires accessibility events and if it is reported to accessibility services.
91   */
92  importantForAccessibility?:
93    | ('auto' | 'yes' | 'no' | 'no-hide-descendants')
94    | undefined;
95
96  /**
97   * A value indicating whether the accessibility elements contained within
98   * this accessibility element are hidden.
99   */
100  'aria-hidden'?: boolean | undefined;
101
102  'aria-live'?: ('polite' | 'assertive' | 'off') | undefined;
103  'aria-modal'?: boolean | undefined;
104
105  /**
106   * Indicates to accessibility services to treat UI component like a specific role.
107   */
108  role?: Role;
109}
110
111export type AccessibilityActionInfo = Readonly<{
112  name: AccessibilityActionName | string;
113  label?: string | undefined;
114}>;
115
116export type AccessibilityActionName =
117  /**
118   * Generated when a screen reader user double taps the component.
119   */
120  | 'activate'
121  /**
122   * Generated when a screen reader user increments an adjustable component.
123   */
124  | 'increment'
125  /**
126   * Generated when a screen reader user decrements an adjustable component.
127   */
128  | 'decrement'
129  /**
130   * Generated when a TalkBack user places accessibility focus on the component and double taps and holds one finger on the screen.
131   * @platform android
132   */
133  | 'longpress'
134  /**
135   * Generated when a VoiceOver user places focus on or inside the component and double taps with two fingers.
136   * @platform ios
137   * */
138  | 'magicTap'
139  /**
140   * Generated when a VoiceOver user places focus on or inside the component and performs a two finger scrub gesture (left, right, left).
141   * @platform ios
142   * */
143  | 'escape';
144
145export type AccessibilityActionEvent = NativeSyntheticEvent<
146  Readonly<{
147    actionName: string;
148  }>
149>;
150
151export interface AccessibilityState {
152  /**
153   * When true, informs accessible tools if the element is disabled
154   */
155  disabled?: boolean | undefined;
156  /**
157   * When true, informs accessible tools if the element is selected
158   */
159  selected?: boolean | undefined;
160  /**
161   * For items like Checkboxes and Toggle switches, reports their state to accessible tools
162   */
163  checked?: boolean | 'mixed' | undefined;
164  /**
165   *  When present, informs accessible tools if the element is busy
166   */
167  busy?: boolean | undefined;
168  /**
169   *  When present, informs accessible tools the element is expanded or collapsed
170   */
171  expanded?: boolean | undefined;
172}
173
174export interface AccessibilityValue {
175  /**
176   * The minimum value of this component's range. (should be an integer)
177   */
178  min?: number | undefined;
179
180  /**
181   * The maximum value of this component's range. (should be an integer)
182   */
183  max?: number | undefined;
184
185  /**
186   * The current value of this component's range. (should be an integer)
187   */
188  now?: number | undefined;
189
190  /**
191   * A textual description of this component's value. (will override minimum, current, and maximum if set)
192   */
193  text?: string | undefined;
194}
195
196export type AccessibilityRole =
197  | 'none'
198  | 'button'
199  | 'togglebutton'
200  | 'link'
201  | 'search'
202  | 'image'
203  | 'keyboardkey'
204  | 'text'
205  | 'adjustable'
206  | 'imagebutton'
207  | 'header'
208  | 'summary'
209  | 'alert'
210  | 'checkbox'
211  | 'combobox'
212  | 'menu'
213  | 'menubar'
214  | 'menuitem'
215  | 'progressbar'
216  | 'radio'
217  | 'radiogroup'
218  | 'scrollbar'
219  | 'spinbutton'
220  | 'switch'
221  | 'tab'
222  | 'tabbar'
223  | 'tablist'
224  | 'timer'
225  | 'list'
226  | 'toolbar';
227
228export interface AccessibilityPropsAndroid {
229  /**
230   * Indicates to accessibility services whether the user should be notified when this view changes.
231   * Works for Android API >= 19 only.
232   * See http://developer.android.com/reference/android/view/View.html#attr_android:accessibilityLiveRegion for references.
233   * @platform android
234   */
235  accessibilityLiveRegion?: 'none' | 'polite' | 'assertive' | undefined;
236
237  /**
238   * Controls how view is important for accessibility which is if it fires accessibility events
239   * and if it is reported to accessibility services that query the screen.
240   * Works for Android only. See http://developer.android.com/reference/android/R.attr.html#importantForAccessibility for references.
241   *
242   * Possible values:
243   *      'auto' - The system determines whether the view is important for accessibility - default (recommended).
244   *      'yes' - The view is important for accessibility.
245   *      'no' - The view is not important for accessibility.
246   *      'no-hide-descendants' - The view is not important for accessibility, nor are any of its descendant views.
247   */
248  importantForAccessibility?:
249    | 'auto'
250    | 'yes'
251    | 'no'
252    | 'no-hide-descendants'
253    | undefined;
254
255  /**
256   * A reference to another element `nativeID` used to build complex forms. The value of `accessibilityLabelledBy` should match the `nativeID` of the related element.
257   * @platform android
258   */
259  accessibilityLabelledBy?: string | string[] | undefined;
260}
261
262export interface AccessibilityPropsIOS {
263  /**
264   * A Boolean value indicating whether the accessibility elements contained within this accessibility element
265   * are hidden to the screen reader.
266   * @platform ios
267   */
268  accessibilityElementsHidden?: boolean | undefined;
269
270  /**
271   * A Boolean value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver.
272   * @platform ios
273   */
274  accessibilityViewIsModal?: boolean | undefined;
275
276  /**
277   * When accessibile is true, the system will invoke this function when the user performs the escape gesture (scrub with two fingers).
278   * @platform ios
279   */
280  onAccessibilityEscape?: (() => void) | undefined;
281
282  /**
283   * When `accessible` is true, the system will try to invoke this function when the user performs accessibility tap gesture.
284   * @platform ios
285   */
286  onAccessibilityTap?: (() => void) | undefined;
287
288  /**
289   * When accessible is true, the system will invoke this function when the user performs the magic tap gesture.
290   * @platform ios
291   */
292  onMagicTap?: (() => void) | undefined;
293
294  /**
295   * https://reactnative.dev/docs/accessibility#accessibilityignoresinvertcolorsios
296   * @platform ios
297   */
298  accessibilityIgnoresInvertColors?: boolean | undefined;
299
300  /**
301   * By using the accessibilityLanguage property, the screen reader will understand which language to use while reading the element's label, value and hint. The provided string value must follow the BCP 47 specification (https://www.rfc-editor.org/info/bcp47).
302   * https://reactnative.dev/docs/accessibility#accessibilitylanguage-ios
303   * @platform ios
304   */
305  accessibilityLanguage?: string | undefined;
306}
307
308export type Role =
309  | 'alert'
310  | 'alertdialog'
311  | 'application'
312  | 'article'
313  | 'banner'
314  | 'button'
315  | 'cell'
316  | 'checkbox'
317  | 'columnheader'
318  | 'combobox'
319  | 'complementary'
320  | 'contentinfo'
321  | 'definition'
322  | 'dialog'
323  | 'directory'
324  | 'document'
325  | 'feed'
326  | 'figure'
327  | 'form'
328  | 'grid'
329  | 'group'
330  | 'heading'
331  | 'img'
332  | 'link'
333  | 'list'
334  | 'listitem'
335  | 'log'
336  | 'main'
337  | 'marquee'
338  | 'math'
339  | 'menu'
340  | 'menubar'
341  | 'menuitem'
342  | 'meter'
343  | 'navigation'
344  | 'none'
345  | 'note'
346  | 'option'
347  | 'presentation'
348  | 'progressbar'
349  | 'radio'
350  | 'radiogroup'
351  | 'region'
352  | 'row'
353  | 'rowgroup'
354  | 'rowheader'
355  | 'scrollbar'
356  | 'searchbox'
357  | 'separator'
358  | 'slider'
359  | 'spinbutton'
360  | 'status'
361  | 'summary'
362  | 'switch'
363  | 'tab'
364  | 'table'
365  | 'tablist'
366  | 'tabpanel'
367  | 'term'
368  | 'timer'
369  | 'toolbar'
370  | 'tooltip'
371  | 'tree'
372  | 'treegrid'
373  | 'treeitem';
374