@procore/core-react
Version:
React library of Procore Design Guidelines
215 lines (214 loc) • 9.54 kB
TypeScript
import type { AriaAttributes } from 'react';
import type { OverlayTriggerRole } from './OverlayTrigger.types';
declare type GetA11yProps = (props: {
role: OverlayTriggerRole;
isVisible: boolean;
overlayId: string;
}) => AriaAttributes & {
id?: string;
};
export declare function getA11yPreset(role?: OverlayTriggerRole | 'alertdialog'): {
getOverlayProps: GetA11yProps;
getTriggerProps: GetA11yProps;
};
declare type LabelConfig = {
'aria-describedby'?: string;
'aria-details'?: string;
'aria-labelledby'?: string;
'aria-label'?: string;
/**
* ID for the widget itself
*/
id?: string;
};
declare type DialogBase = LabelConfig & {
isOpen: boolean;
role?: 'dialog' | 'alertdialog';
};
declare type NonModalDialogConfig = DialogBase & {
'aria-modal'?: never | false;
};
declare type ModalDialogConfig = DialogBase & {
/**
* @a11y This will add `aria-modal={true}` and rely on browsers to
* handle making outside content inert.
* @default false
*/
'aria-modal': true;
};
declare type ModalDialogLikeConfig = NonModalDialogConfig | ModalDialogConfig;
declare type OverlayTriggerA11yConfig = LabelConfig & {
/**
* Assure `aria-hidden` is not applied. A code side-effect
* from `ariaHideOutside` hiding everthing outside the scope.
*/
alwaysAriaVisible?: boolean;
/**
* When properties should be passed to the overlay UI itself,
* and not the wrapper element.
*/
canPropOverlayUp: boolean;
isOpen: boolean;
role?: OverlayTriggerRole;
};
/**
* Manages labelling for an element and the other DOM. Defaults an ID for `aria-labelledby` usage.
*
* When `aria-label` and `aria-labelledby` both exist, it combines them into `aria-labelledby` for a screen reader chain.
* @link [W3 naming with aria-labelledby](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#naming_with_aria-labelledby)
*/
export declare function useLabelled(props?: LabelConfig): {
descriptionProps: {
id: string | undefined;
};
labelProps: {
id: string | undefined;
};
widgetProps: {
'aria-describedby': string | undefined;
'aria-details': string | undefined;
id?: string | undefined;
'aria-label'?: string | undefined;
'aria-labelledby'?: string | undefined;
};
};
/**
* Cover the label links for the trigger (button), the popup element (dialog), and the popup element title (heading).
* Similar to [React Aria useOverlayTrigger](https://github.com/adobe/react-spectrum/blob/main/packages/%40react-aria/overlays/src/useOverlayTrigger.ts)
* but with element title support.
* @link [MDN aria-haspopup](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup)
*/
export declare function useLabelledPopup({ 'aria-describedby': ariaDescribedby, 'aria-details': ariaDetails, 'aria-labelledby': ariaLabelledby, 'aria-label': ariaLabel, id: id_, isOpen, type, popupRole, popupId: popupId_, }: LabelConfig & {
isOpen: boolean;
popupId?: string;
type?: 'button' | 'combobox';
popupRole: 'dialog' | 'menu' | 'listbox';
}): {
labelProps: {
id: string | undefined;
};
popupProps: {
"aria-activedescendant"?: string | undefined;
"aria-atomic"?: (boolean | "false" | "true") | undefined;
"aria-autocomplete"?: "none" | "both" | "inline" | "list" | undefined;
"aria-braillelabel"?: string | undefined;
"aria-brailleroledescription"?: string | undefined;
"aria-busy"?: (boolean | "false" | "true") | undefined;
"aria-checked"?: boolean | "mixed" | "false" | "true" | undefined;
"aria-colcount"?: number | undefined;
"aria-colindex"?: number | undefined;
"aria-colindextext"?: string | undefined;
"aria-colspan"?: number | undefined;
"aria-controls"?: string | undefined;
"aria-current"?: boolean | "time" | "page" | "false" | "true" | "step" | "location" | "date" | undefined;
"aria-describedby": string | undefined;
"aria-description"?: string | undefined;
"aria-details": string | undefined;
"aria-disabled"?: (boolean | "false" | "true") | undefined;
"aria-dropeffect"?: "link" | "none" | "copy" | "move" | "execute" | "popup" | undefined;
"aria-errormessage"?: string | undefined;
"aria-expanded"?: (boolean | "false" | "true") | undefined;
"aria-flowto"?: string | undefined;
"aria-grabbed"?: (boolean | "false" | "true") | undefined;
"aria-haspopup"?: boolean | "dialog" | "menu" | "listbox" | "grid" | "false" | "true" | "tree" | undefined;
"aria-hidden"?: (boolean | "false" | "true") | undefined;
"aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
"aria-keyshortcuts"?: string | undefined;
"aria-label"?: string | undefined;
"aria-labelledby"?: string | undefined;
"aria-level"?: number | undefined;
"aria-live"?: "off" | "assertive" | "polite" | undefined;
"aria-modal"?: (boolean | "false" | "true") | undefined;
"aria-multiline"?: (boolean | "false" | "true") | undefined;
"aria-multiselectable"?: (boolean | "false" | "true") | undefined;
"aria-orientation"?: "horizontal" | "vertical" | undefined;
"aria-owns"?: string | undefined;
"aria-placeholder"?: string | undefined;
"aria-posinset"?: number | undefined;
"aria-pressed"?: boolean | "mixed" | "false" | "true" | undefined;
"aria-readonly"?: (boolean | "false" | "true") | undefined;
"aria-relevant"?: "text" | "all" | "additions" | "additions removals" | "additions text" | "removals" | "removals additions" | "removals text" | "text additions" | "text removals" | undefined;
"aria-required"?: (boolean | "false" | "true") | undefined;
"aria-roledescription"?: string | undefined;
"aria-rowcount"?: number | undefined;
"aria-rowindex"?: number | undefined;
"aria-rowindextext"?: string | undefined;
"aria-rowspan"?: number | undefined;
"aria-selected"?: (boolean | "false" | "true") | undefined;
"aria-setsize"?: number | undefined;
"aria-sort"?: "other" | "none" | "ascending" | "descending" | undefined;
"aria-valuemax"?: number | undefined;
"aria-valuemin"?: number | undefined;
"aria-valuenow"?: number | undefined;
"aria-valuetext"?: string | undefined;
id?: string | undefined;
role: "dialog" | "menu" | "listbox";
};
triggerProps: AriaAttributes & {
id?: string | undefined;
};
};
/**
* For dialog experiences:
* - Has role dialog and aria linked title props
* - Focus management props to work with FocusScope
*
* For modal dialog experiences (full screen locked experiences):
* - what dialog above does
* - adds aria-modal="true"
* - this hook does not determine where to mount or how many modals are open
*
* For either experiences, you still MUST support a way to close by mouse and keyboard.
*
* Using `aria-modal`, you need to keep additional overlay content inside, so
* portals must be smart enough to know where other overlays
* like tooltips or toasts should go to remain visible to screen readers (inside the aria-modal).
*
* Setting aria-modal="true" tells assistive technologies to let the user know the ability to interact with,
* or access other content on the page requires the modal dialog to be closed or otherwise lose focus.
* Modal dialogs are when content is displayed and the user's interaction is limited to only that section until it is dismissed.
* [MDN aria modal](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal).
*/
export declare function useModalDialogLike({ 'aria-describedby': ariaDescribedby, 'aria-details': ariaDetails, 'aria-labelledby': ariaLabelledby, 'aria-label': ariaLabel, 'aria-modal': ariaModal, id, isOpen, role, }: ModalDialogLikeConfig): {
dialogProps: {
id: string | undefined;
role: "dialog" | "alertdialog";
tabIndex: number;
'aria-describedby': string | undefined;
'aria-details': string | undefined;
'aria-label'?: string | undefined;
'aria-labelledby'?: string | undefined;
'aria-modal': boolean | undefined;
};
labelProps: {
id: string | undefined;
};
focusScopeProps: {
autoFocus: boolean;
contain: boolean;
restoreFocus: boolean;
};
};
/**
* Takes many roles and determines props necessary for DOM/components.
* **Side effect of role="dialog"**, current and any content added later
* outside of the element (like by portals) will get `aria-hidden=true`
* to replace the `aria-modal=true` `inert` nature.
* @see useModalDialogLike */
export declare function useOverlayTriggerA11y({ alwaysAriaVisible, 'aria-describedby': ariaDescribedby, 'aria-details': ariaDetails, 'aria-labelledby': ariaLabelledby, 'aria-label': ariaLabel, canPropOverlayUp, id: id_, isOpen, role, }: OverlayTriggerA11yConfig): {
focusScopeProps: {
autoFocus?: boolean | undefined;
contain?: boolean | undefined;
restoreFocus?: boolean | undefined;
};
labelProps: {
id: string | undefined;
};
overlayProps: {};
portalProps: {};
triggerProps: AriaAttributes & {
id?: string | undefined;
};
wrapperProps: {};
};
export {};