[PositionedOverlay] Add support for horizontal positioning

[chloerice]

WHY are these changes introduced?

This PR unblocks the new HoverCard component, which needs to be able to be positioned left and right of table cells.

WHAT is this pull request doing?

Adds support for horizontal positioning of positioned overlays.

Demos

Responsive vertical alignment when positioned horizontally	right	left	below	above
hovercard-demo-position-right-responsive-alignment.mp4

How to 🎩

🖥 Local development instructions
🗒 General tophatting guidelines
📄 Changelog guidelines

Click to view Playground code used for the above demos

import React, {useState} from 'react';
import {LocationIcon, OrderIcon} from '@shopify/polaris-icons';

import type {PopoverProps} from '../src';
import {
  Page,
  ButtonGroup,
  Box,
  Button,
  Popover,
  Icon,
  Link,
  Text,
  BlockStack,
  InlineStack,
  Card,
  Layout,
} from '../src';

export function Playground() {
  return (
    <Page title="Playground">
      <Layout>
        <Layout.Section>
          <PopoverPositioneExample />
        </Layout.Section>
      </Layout>
    </Page>
  );
}

export function PopoverPositioneExample() {
  const [active, setActive] = useState(false);
  const [position, setPosition] =
    useState<PopoverProps['preferredPosition']>('right');

  const handleChangePosition =
    (position: PopoverProps['preferredPosition']) => () => {
      setPosition(position);
    };

  const toggleActive = (active: boolean) => () => {
    setActive(active);
  };

  const activator = (
    <Link removeUnderline url="#" onClick={toggleActive(true)}>
      Saul Goodman
    </Link>
  );

  const customerDetailPreviewContent = (
    <Box padding="400">
      <BlockStack gap="400">
        <BlockStack gap="0">
          <Text as="span" variant="headingSm">
            <Link removeUnderline>Saul Goodman</Link>
          </Text>
          <Text as="span" variant="bodyMd">
            <Link url="mailto:help@bettercallsaul.com">
              help@bettercallsaul.com
            </Link>
          </Text>
          <Text as="p" variant="bodyMd">
            <Link url="tel:+1505-842-5662">+1 505-842-5662</Link>
          </Text>
        </BlockStack>
        <Box width="100%">
          <BlockStack gap="100">
            <InlineStack wrap={false} gap="100" align="start">
              <Icon tone="subdued" source={LocationIcon} />
              <Text tone="subdued" as="p">
                Albequerque, NM, USA
              </Text>
            </InlineStack>
            <InlineStack wrap={false} gap="100" align="start">
              <Box>
                <Icon tone="subdued" source={OrderIcon} />
              </Box>
              <Text tone="subdued" as="p">
                8 Orders
              </Text>
            </InlineStack>
          </BlockStack>
        </Box>
      </BlockStack>
    </Box>
  );

  const positionControlBar = (
    <BlockStack gap="100" inlineAlign="center">
      <Box id="Filler" minHeight="200px" />
      <Text as="p" tone="subdued">
        Use the buttons below to change the preferred popover position
      </Text>
      <ButtonGroup variant="segmented">
        <Button
          pressed={position === 'left'}
          onClick={handleChangePosition('left')}
        >
          Left
        </Button>
        <Button
          pressed={position === 'right'}
          onClick={handleChangePosition('right')}
        >
          Right
        </Button>
        <Button
          pressed={position === 'above'}
          onClick={handleChangePosition('above')}
        >
          Above
        </Button>
        <Button
          pressed={position === 'below'}
          onClick={handleChangePosition('below')}
        >
          Below
        </Button>
      </ButtonGroup>
    </BlockStack>
  );

  return (
    <InlineStack align="center" blockAlign="center">
      <BlockStack gap="500">
        {positionControlBar}

        <Card>
          <BlockStack gap="300">
            <Text as="h2" variant="headingSm">
              Customer
            </Text>
            <Popover
              active={active}
              preferredPosition={position}
              preferredAlignment="left"
              activator={activator}
              onClose={toggleActive(false)}
            >
              {customerDetailPreviewContent}
            </Popover>
          </BlockStack>
        </Card>
      </BlockStack>
    </InlineStack>
  );
}

🎩 checklist

• Tested a snapshot
• Tested on mobile
• Tested on multiple browsers
• Tested for accessibility
• Updated the component's README.md with documentation changes
• Tophatted documentation changes in the style guide

[chloerice]

Though these could all technically move to CSS variables set and updated in the CSS, these properties still need to be set on the style property otherwise there is cascade collision with children.

[chloerice]

This was already defined as a variable on line 265 (line 274 now), so removed the redundancy.

[chloerice]

This math was causing the available vertical space to be undercalculated, causing the overlay to switch positions sooner than necessary. I fixed this and made the variable names clearer so it's easier to understand what's going on here.

[jesstelford]

CSS Custom Properties have a default value of initial when not set, so defining these on :root is the same as not defining them at all.

Suggested change

	:root {
	// stylelint-disable polaris/conventions/polaris/custom-property-allowed-list -- PositionedOverlay CSS Properties; Supports consuming component styles tying into changes in order to animate without hacky JavaScript timers and forcing reflow
	--pc-positioned-overlay-top: initial;
	--pc-positioned-overlay-bottom: initial;
	// stylelint-enable
	}

[chloerice]

Thanks Jess! They're initialized so they can be updated in the PositionedOverlay.tsx. So are you saying they don't need to exist before they're used? (they're consumed in HoverCardOverlay so that the animation of top/bottom can be pure CSS instead the hacky forced reflow with JS like Popover does.

[translation-platform]

Localization quality issues found

The following issues may affect the quality of localized translations if they are not addressed:

• The value Clear for key Polaris.ActionList.SearchField.clearButtonLabel is very short. Short strings are more likely to be misunderstood by translators without context. Please provide additional context for the translators if possible.
• The value Search for key Polaris.ActionList.SearchField.search is very short. Short strings are more likely to be misunderstood by translators without context. Please provide additional context for the translators if possible.
• The value Search actions for key Polaris.ActionList.SearchField.placeholder is very short. Short strings are more likely to be misunderstood by translators without context. Please provide additional context for the translators if possible.

Please look out for other instances of this issue in your PR and fix them as well if possible.

Questions about these messages? Hop in the #help-localization Slack channel.