import { V1Flyout } from '@uhg-abyss/web/ui/Flyout';

children

position

label

indent

variant

() => {
  const Container = React.useMemo(
    () =>
      styled('div', {
        padding: '$web.semantic.spacing.scale.md',
      }),
    []
  );

  return (
    <React.Fragment>
      <Text>
        V1Flyout example starts on the right of the screen. See 'V1Flyout Label'.
      </Text>
      <br />
      <br />
      <Text>
        This V1Flyout can be opened with the access key 'F'; the underlined 'F' in the label is to indicate this.
      </Text>
      <br/>
      <Text>
      Press Ctrl + Option + F on Mac (Chrome/Safari) or Alt + F on Windows (Chrome).</Text>
      <br />
      <Text>
        Press Ctrl + Option + F on Mac (Chrome/Safari) or Alt + F on Windows (Chrome).
      </Text>
      <br />
      <Text>
        See the Access Key section below for more details, including a full list of shortcuts.
      </Text>

      <V1Flyout
        position="right"
        label="V1Flyout Label"
        indent="60%"
        variant="filled"
      >
        <Container>
          <Text>Here is the V1Flyout content from the sandbox example.</Text>
        </Container>
      </V1Flyout>
    </React.Fragment>
  );
}

Access key

The accessKey prop sets a keyboard shortcut to open the V1Flyout from anywhere on the page. This is recommended for accessibility purposes, for users who navigate with the keyboard.

By default, accessKey is set to the first character of the label prop, assuming a label is provided. As a visual indicator, the first character of the label is underlined and bolded to show the access key. To disable this, use the disableUnderlineAccessKey prop.

If a custom access key is set via the prop, no character is underlined/bolded in the label.

To disable the accessKey entirely, set the prop to an empty string.

The value must consist of a single printable character. This forms part of a keyboard shortcut, which varies depending on the browser and operating system.

For Chrome and Safari on Mac, the shortcut is Ctrl + Option + key. For Chrome on Windows, the shortcut is Alt + key.

See the MDN Web Docs for more information, including browser-specific shortcuts.

Button only

The primary function of the V1Flyout component, as the title suggests, is to expand a small V1Flyout drawer via a sticky button.

Additionally, the V1Flyout component can be used as a button, to do something like open a modal or a link. This is achieved by passing the buttonOnly prop.

Use the onClick prop to customize the action of the button, such as to open a modal.

To use the button as a link, see the href prop.

Variant

The variant prop offers two color/styling options for the button - 'filled' and 'outlined'.

'filled' is designed for the classic flyout scenario where a small drawer can expand out.

'outlined' is a secondary style, and is useful for actions such as going to an external feedback form via the onClick callback. It can technically be used in the same way as the filled variant, too. For example, if there are 2 different Flyouts on the same page, one can be filled and the other outlined.

Positioning

Use the position prop to change where the V1Flyout is anchored on the screen. Options include 'right' or 'bottom' The default position is 'right'.

The indent prop offsets the V1Flyout from its anchored edge. This prop accepts values like pixels ('px') or percentages ('%') to represent the offset distance. The default indent is '35%'.

• With position="right", increasing the indent value moves the V1Flyout vertically, away from the bottom of the screen.
• For position="bottom", increasing the indent values moves the V1Flyout horizontally away from the right side of the screen.

<V1Flyout> can be anchored to either the right side or bottom of a screen, as specified by the required position prop.

Further customization of the <V1Flyout> position can be made with the indent prop. If the position is 'bottom', the indent specifies how far up from the bottom of the screen the <V1Flyout> is positioned. If the position is 'right', the indent specifies how far up from the right the <V1Flyout> is positioned.

indent examples include '30px' or '50%'.

href

The href prop allows the V1Flyout to act as a link. When the V1Flyout is clicked, the user is redirected to the specified URL.

See the ButtonOnly example for a use case.

Height and width

The height and width props set the size of the V1Flyout's opened content drawer.

The Abyss design team has specified a recommended height and width:

• height should be between 208px and 320px (default: 208px)
• width should be between 400px and 504px (default: 400px)

When the variant is 'filled', and the position is 'right', the height of the button is fixed to match the height of the opened menu. Otherwise, the button is sized dynamically.

Icon

An icon can be added to the left side of the V1Flyout button by passing an Icon or IconSymbol component to the icon prop.

The left icon is customizable. The right icon is reserved for a chevron icon that can be toggled on or off with the showArrowIcon prop - see below.

For examples, see Positioning or Variant.

Show arrow icon

The showArrowIcon prop displays a chevron icon on the right side of the V1Flyout button. This is useful for indicating that the button expands a drawer.

Overflow scrolling

When the V1Flyout is expanded, the V1Flyout content is scrollable if the content exceeds the height of the V1Flyout.

Content focus

The contentFocus prop allows the V1Flyout content container to receive focus when the V1Flyout is expanded. Then, keyboard users can use the tab key to navigate to the content.

This is intended to be used if the contents of the V1Flyout overflow. Otherwise, it adds an unnecessary tab stop.

If there are interactive elements placed within the V1Flyout content, these will already appear in the tab order, regardless of the contentFocus prop. For example, form controls (<input>, <textarea>, <select>), Links (<a>), and Buttons (<button>) appear in the tab order by default.

Responsiveness

When the screen hits a breakpoint of 744px or smaller, to ensure visibility of the component, we instead display the expanded form as a full-screen ModalDialog.

V1Flyout Props

Prop Name	Type	Default	Description
accessKey	string	First char of label	Set the access key to open the V1Flyout menu with a keyboard shortcut
buttonOnly	boolean	false	If true, the V1Flyout button does not expand the content drawer
children	node	-	Element displayed when the V1Flyout is expanded
color	string	$web.semantic.color.surface.interactive.standards.rest.default.primary	Set the color of the V1Flyout Button
contentFocus	boolean	false	If true, the V1Flyout content container can receive focus when the V1Flyout is expanded
disableUnderlineAccessKey	boolean	false	If true, the first character is not bolded and underlined to indicate the access key
height	string | number	208px	Set the height of the expanded content
href	string	-	URL to redirect to when the V1Flyout is clicked. Use with buttonOnly
icon	JSX.Element	-	The icon to display on the left side of the V1Flyout button
indent	string	25%	The amount the flyout is shifted from the bottom right corner of the screen
label	string		Title on the V1Flyout button
onClick	function	-	Used to trigger a custom function when the V1Flyout is clicked
position	'right' | 'bottom'	right	Indicate whether the V1Flyout is shown on the bottom or right side of the screen
showArrowIcon	boolean	true	If true, the V1Flyout button displays an arrow icon
variant	'filled' | 'outlined'	filled	Indicate whether the V1Flyout is shown with filled primary button or secondary outlined
width	string | number	400px	Set the width of the expanded content

V1Flyout Classes

Class Name	Description
.abyss-flyout-body-button	Hidden button at the beginning of the HTML body for accessibility
.abyss-flyout-button-flex-container	Flex-box container within the button
.abyss-flyout-button-icon	Custom icon in the button
.abyss-flyout-content-container	V1Flyout content container when expanded
.abyss-flyout-expand-icon	Chevron icon in the button
.abyss-flyout-responsive-content-drawer-container	V1Flyout drawer container when expanded in a small screen size
.abyss-flyout-root-container	V1Flyout root element
.abyss-flyout-trigger-button	V1Flyout button to click to expand or perform other actions

The V1Flyout component is composed of two parts: a "sticky" button positioned on the side of the browser window and modal drawer (dialog) that displayed when activated. When collapsed or displayed, the V1Flyout button and modal overlay the main content.

Communicating sticky button presence and keyboard access

Since the button is sticky, repositioned to the sides of browser window, and added to the end of the HTML. As result many users, especially those using screen readers, may not realize the button even exists. Keyboard users, if they know the button exists, would have difficulty accessing it in the focus order since is at the end of HTML <body>.

Skip links added to top of page

To address both issues, skip links are added to the very top of the page and (ideally) before any "skip to main content" option. Screen reader users are informed of these options at the start of the page. Minor changes for some browsers were made to address in this link to help avoid known conflicts (See BrAT Accesskey Variations below).

Accesskey keyboard shortcut

The skip link also includes the keyboard shortcut to access the V1Flyout. This uses the standard HTML accesskey which should be familiar to them and their variations (See BrAT Accesskey Variations below). By default, the first letter of V1Flyout.Label becomes the shortcut key. By default, it is also underlined in the sticky button as a reminder for sighted user. These settings can be overridden (See the Access Key section in the Overview tab).

Closing V1Flyout returns to previous location

Like modal dialogs, closing a V1Flyout (should) return the focus to whatever element had it when it was opened. V1Flyout implements this so focus returns to the element that had it when closed. Flyouts can be closed using Escape, pressing Enter on the flyout button, or pressing the flyout accesskey combination again.

WAI-ARIA dialog pattern

The closest WAI-ARIA design pattern is the Dialog (Modal) Pattern and Modal Dialog Example. WAI-ARIA currently (WAI-AIRA 1.1 as of 8/1/2024) has no equivalent to the sticky button and its keyboard access. The design and implementation used were created to address the issue covered above.

BrAT Accesskey Variations

• Windows browsers (Chrome, Edge, Firefox) and screen readers (NVDA, JAWS)

  • Minor accesskey variation: Addition of Shift key

    Windows accesskey for Chrome and Edge relies on Alt alone. This can cause conflicts accessing some characters Chromium browsers use for their keyboard shortcuts.
    
    

    Firefox browser implements accesskey requires using Alt + Shift. Using Alt + Shift with the character addresses the issue with letter keys and works the same in all three browsers. This is why the skip links at the top of the page include Shift on Chromium browsers even though they may not be necessary.
    
    

    Example: On this page, the sandbox example uses accesskey="F" to access the "V1Flyout Label" example on the right side of this window. Using Edge and Chrome Alt + F opens the File menu. Using Alt + Shift + F accesses V1Flyout Label as intended.
    
    

• MacOS browsers (Safari, Chrome) and screen readers (VoiceOver)

  • VoiceOver conflict with browser accesskey default
    • MacOS uses Control + Option and this shown in skip link in Safari and Chrome browsers.
    • VoiceOver uses Control + Option as its modifier keys creating a conflict when used in the browsers (discussed below)
      
      
  • Safari
    • Keyboard without VoiceOver: Control + Option + Letter (default)
    • Keyboard with VoiceOver: Control + Letter ONLY
      • Apple modifies Safari's HTML accesskey implementation to use only Control when VoiceOver is running
      • Using modified accesskey using Control + [letter] works as described above including resetting focus to originally focused element using Escape, accesskey, and flyout button
      • Note: Once activated, the Control-only accesskey modification is persistent even if VoiceOver is turned off. Restart Safari without VoiceOver to reset accesskey to Control + Option.
        
        
  • Chrome
    • Keyboard without VoiceOver: Control + Option + Letter (default)
    • Keyboard with VoiceOver: accesskey "effectively disabled"
      • Unlike Safari, the HTML accesskey modifier combination remains Control + Option
      • To use this accesskey combination requires using VoiceOver pass-through mode using Control + Option + Tab
        • Then use normal Control + Option accesskey combination to open flyout. Operation then works as described resetting focus to originally focused element using Escape, accesskey, and flyout button
      • Example: To access the V1Flyout Label example requires pressing Control + Option + Tab, then Control + Option + F
        
        

• For more information about accesskey BrAT implementations see: Accesskey Accessibility Demo (pauljadam.com)

Keyboard Interactions

Key	Description
Enter	Executes the V1Flyout button trigger to expand or close (when focus is on button)
Space	Executes the V1Flyout button trigger to expand or close (when focus is on button)
Esc	Closes the V1Flyout
Tab	Moves focus to V1Flyout content window when using contentFocus or to focusable element when present in content