@instructure/ui-popover 11.6.0 → 11.6.1-snapshot-129

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-popover",
-  "version": "11.6.0",
+  "version": "11.6.1-snapshot-129",
   "description": "A component for hiding or showing content based on user interaction.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -16,28 +16,28 @@
   "dependencies": {
     "@babel/runtime": "^7.27.6",
     "keycode": "^2.2.1",
-    "@instructure/console": "11.6.0",
-    "@instructure/emotion": "11.6.0",
-    "@instructure/ui-a11y-utils": "11.6.0",
-    "@instructure/ui-dialog": "11.6.0",
-    "@instructure/shared-types": "11.6.0",
-    "@instructure/ui-dom-utils": "11.6.0",
-    "@instructure/ui-i18n": "11.6.0",
-    "@instructure/ui-position": "11.6.0",
-    "@instructure/ui-utils": "11.6.0",
-    "@instructure/ui-view": "11.6.0",
-    "@instructure/uid": "11.6.0",
-    "@instructure/ui-react-utils": "11.6.0"
+    "@instructure/console": "11.6.1-snapshot-129",
+    "@instructure/emotion": "11.6.1-snapshot-129",
+    "@instructure/ui-a11y-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-dialog": "11.6.1-snapshot-129",
+    "@instructure/shared-types": "11.6.1-snapshot-129",
+    "@instructure/ui-dom-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-i18n": "11.6.1-snapshot-129",
+    "@instructure/ui-position": "11.6.1-snapshot-129",
+    "@instructure/ui-react-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-view": "11.6.1-snapshot-129",
+    "@instructure/uid": "11.6.1-snapshot-129"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "15.0.7",
     "@testing-library/user-event": "^14.6.1",
     "vitest": "^3.2.2",
-    "@instructure/ui-axe-check": "11.6.0",
-    "@instructure/ui-babel-preset": "11.6.0",
-    "@instructure/ui-color-utils": "11.6.0",
-    "@instructure/ui-themes": "11.6.0"
+    "@instructure/ui-axe-check": "11.6.1-snapshot-129",
+    "@instructure/ui-babel-preset": "11.6.1-snapshot-129",
+    "@instructure/ui-color-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-themes": "11.6.1-snapshot-129"
   },
   "peerDependencies": {
     "react": ">=18 <=19"
@@ -47,17 +47,39 @@
   },
   "sideEffects": false,
   "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "import": "./es/index.js",
-      "require": "./lib/index.js",
-      "default": "./es/index.js"
-    },
     "./lib/*": "./lib/*",
     "./es/*": "./es/*",
     "./types/*": "./types/*",
     "./package.json": "./package.json",
-    "./src/*": "./src/*"
+    "./src/*": "./src/*",
+    ".": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./v11_6": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./v11_7": {
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
+    },
+    "./latest": {
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
+    }
   },
   "scripts": {
     "lint": "ui-scripts lint",

package/src/Popover/{index.tsx → v1/index.tsx}

@@ -30,7 +30,7 @@ import {
   parsePlacement,
   mirrorHorizontalPlacement
 } from '@instructure/ui-position'
-import { ContextView, View } from '@instructure/ui-view'
+import { ContextView, View } from '@instructure/ui-view/v11_6'
 import { Dialog } from '@instructure/ui-dialog'
 import { textDirectionContextConsumer } from '@instructure/ui-i18n'
 import {
@@ -55,17 +55,17 @@ import { logError as error } from '@instructure/console'
 import { FocusRegion } from '@instructure/ui-a11y-utils'
 
 import type { RequestAnimationFrameType } from '@instructure/ui-dom-utils'
-import type { ViewProps, ContextViewProps } from '@instructure/ui-view'
+import type { ViewProps, ContextViewProps } from '@instructure/ui-view/v11_6'
 import type { PositionProps } from '@instructure/ui-position'
 import type { DialogProps } from '@instructure/ui-dialog'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'
 
-import type { PopoverProps, PopoverState } from './props'
-import { allowedProps } from './props'
+import type { PopoverProps, PopoverState } from '../v1/props'
+import { allowedProps } from '../v1/props'
 import type { Renderable } from '@instructure/shared-types'
 /**
 ---

package/src/Popover/v2/README.md

@@ -0,0 +1,455 @@
+---
+describes: Popover
+---
+
+Popovers hide or show content as a result of user interaction, such as clicking, hovering, or focusing. When opened, the content remains connected to the element that triggered it. If you only need to display a small amount of text-only content, you might consider using a [Tooltip](Tooltip). If you need to display a larger amount of content, a [Tray](Tray) could be a better choice.
+
+#### Uncontrolled Popover
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [withArrow, setWithArrow] = useState(true)
+  const [shouldAlignArrow, setShouldAlignArrow] = useState(true)
+  const [color, setColor] = useState('primary')
+
+  const toggleWithArrow = () => {
+    setWithArrow((withArrow) => !withArrow)
+  }
+
+  const toggleAlignArrow = () => {
+    setShouldAlignArrow((shouldAlignArrow) => !shouldAlignArrow)
+  }
+
+  const changeColor = (event, color) => {
+    setColor(color)
+  }
+
+  return (
+    <>
+      <FormFieldGroup description="Uncontrolled Popover Example">
+        <Checkbox
+          checked={withArrow}
+          label="With Arrow"
+          onChange={toggleWithArrow}
+        />
+        <Checkbox
+          checked={shouldAlignArrow}
+          label="Align Arrow"
+          onChange={toggleAlignArrow}
+        />
+      </FormFieldGroup>
+      <View display="block" margin="small none">
+        <RadioInputGroup
+          name="color"
+          defaultValue="primary"
+          description="Color:"
+          variant="toggle"
+          size="small"
+          onChange={changeColor}
+        >
+          <RadioInput label="Primary" value="primary" />
+          <RadioInput label="Primary inverse" value="primary-inverse" />
+        </RadioInputGroup>
+      </View>
+      <View display="block" as="div" margin="small">
+        <Popover
+          renderTrigger={
+            <Link aria-describedby="tip">Hover or focus me</Link>
+          }
+          shouldRenderOffscreen
+          shouldReturnFocus={false}
+          withArrow={withArrow}
+          shouldAlignArrow={shouldAlignArrow}
+          color={color}
+          placement="top end"
+          onPositioned={() => console.log('positioned')}
+          onShowContent={() => console.log('showing')}
+          onHideContent={() => console.log('hidden')}
+        >
+          <View padding="x-small" display="block" as="div" id="tip">
+            Hello World
+          </View>
+        </Popover>
+      </View>
+    </>
+  )
+}
+render(<Example />)
+```
+
+#### Controlled Popover
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [isShowingContent, setIsShowingContent] = useState(false)
+
+  const usernameRef = useRef(null)
+
+  const renderCloseButton = () => (
+    <CloseButton
+      placement="end"
+      offset="small"
+      onClick={() => setIsShowingContent(false)}
+      screenReaderLabel="Close"
+    />
+  )
+
+  return (
+    <View>
+      <Popover
+        renderTrigger={<Button>Sign In</Button>}
+        isShowingContent={isShowingContent}
+        onShowContent={() => {
+          setIsShowingContent(true)
+        }}
+        onHideContent={() => {
+          setIsShowingContent(false)
+        }}
+        on="click"
+        screenReaderLabel="Popover Dialog Example"
+        shouldContainFocus
+        shouldReturnFocus
+        shouldCloseOnDocumentClick
+        offsetY="16px"
+      >
+        <View padding="medium" display="block" as="form">
+          {renderCloseButton()}
+          <FormFieldGroup description="Log In">
+            <TextInput renderLabel="Username" ref={usernameRef} />
+            <TextInput renderLabel="Password" type="password" />
+          </FormFieldGroup>
+        </View>
+      </Popover>
+    </View>
+  )
+}
+
+render(<Example />)
+```
+
+> Note: Popover can act as a dialog with a close button. With the `shouldContainFocus` property set, it will trap focus inside the Popover.
+
+The `shouldAlignArrow` prop will offset the popover content to adjust for the offset of the arrow. This will override offsetX for start/end placements, and will override offsetY for top/bottom placements.
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [shouldAlignArrow, setShouldAlignArrow] = useState(true)
+
+  const toggleAlignArrow = () => {
+    setShouldAlignArrow((shouldAlignArrow) => !shouldAlignArrow)
+  }
+
+  return (
+    <>
+      <FormFieldGroup description="Align Arrow Example">
+        <Checkbox
+          checked={shouldAlignArrow}
+          label="Align Arrow"
+          onChange={toggleAlignArrow}
+        />
+      </FormFieldGroup>
+      <div
+        style={{
+          paddingBottom: 25,
+          display: 'flex',
+          justifyContent: 'center'
+        }}
+      >
+        <Popover
+          renderTrigger={
+            <div
+              style={{
+                display: 'inline-block',
+                height: '3px',
+                width: '3px',
+                background: 'blue'
+              }}
+            />
+          }
+          isShowingContent={true}
+          placement="end top"
+          shouldAlignArrow={shouldAlignArrow}
+        >
+          <Heading>
+            Small
+            <br />
+            Target
+          </Heading>
+        </Popover>
+      </div>
+    </>
+  )
+}
+
+render(<Example />)
+```
+
+If the `Popover` contains focusable content and should be rendered in the focus order immediately after the trigger, it can be configured using the `shouldFocusContentOnTriggerBlur` prop. Note that the content must be rendered in the correct order in the document (using the `mountNode` prop).
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [isShowingContent, setIsShowingContent] = useState(false)
+
+  return (
+    <div
+      style={{ paddingBottom: 50, display: 'flex', justifyContent: 'center' }}
+    >
+      <Popover
+        renderTrigger={<Button margin="small">Focus Me</Button>}
+        isShowingContent={isShowingContent}
+        onShowContent={() => {
+          setIsShowingContent(true)
+        }}
+        onHideContent={() => {
+          setIsShowingContent(false)
+        }}
+        on={['hover', 'focus']}
+        shouldContainFocus={false}
+        shouldFocusContentOnTriggerBlur={false}
+      >
+        <Button margin="small">Focus Me When Trigger Blurs</Button>
+      </Popover>
+      <div id="container" />
+      <Button id="next" margin="small">
+        Focus Me Next
+      </Button>
+    </div>
+  )
+}
+
+render(<Example />)
+```
+
+#### Custom elements as renderTrigger
+
+Popover and Tooltip attach mouse and focus event listeners to their `renderTrigger` components via props. These need to be propagated to the component for the listeners to work:
+
+```js
+---
+type: example
+---
+const MyComponent = React.forwardRef((props, ref) => {
+  return (
+    <div {...props} ref={ref} style={{ width: '10rem' }}>
+      My custom component
+    </div>
+  )
+})
+
+render(<MyComponent />)
+;<Popover renderTrigger={<MyComponent />}>
+  This text is wrapped by a Popover
+</Popover>
+```
+
+#### Popover playground
+
+```js
+---
+type: example
+---
+const placementsValues = [
+  'top',
+  'end',
+  'bottom',
+  'start',
+  'top start',
+  'start top',
+  'start center',
+  'start bottom',
+  'bottom start',
+  'bottom center',
+  'bottom end',
+  'end bottom',
+  'end center',
+  'end top',
+  'top end',
+  'top center',
+  'center end',
+  'center start'
+]
+
+const shadowValues = ['none', 'resting', 'above', 'topmost']
+
+const Example = () => {
+  const [shouldAlignArrow, setShouldAlignArrow] = useState(true)
+  const [isShowingContent, setIsShowingContent] = useState(true)
+  const [withArrow, setWithArrow] = useState(true)
+  const [placement, setPlacement] = useState('top')
+  const [shadow, setShadow] = useState('topmost')
+  const [color, setColor] = useState('primary')
+
+  const changePlacement = (e, { value }) => {
+    setPlacement(value)
+  }
+
+  const changeShadow = (e, { value }) => {
+    setShadow(value)
+  }
+
+  const toggleWithArrow = () => {
+    setWithArrow((withArrow) => !withArrow)
+  }
+
+  const toggleAlignArrow = () => {
+    setShouldAlignArrow((shouldAlignArrow) => !shouldAlignArrow)
+  }
+
+  const toggleShowContent = () =>
+    setIsShowingContent((isShowingContent) => !isShowingContent)
+
+  const changeColor = (event, value) => {
+    setColor(value)
+  }
+
+  return (
+    <View as="div" background="primary" padding="small">
+      <Flex margin="small small large" justifyItems="space-around">
+        <Flex.Item align="start">
+          <FormFieldGroup description="Popover Example">
+            <Checkbox
+              checked={isShowingContent}
+              label="Show Content"
+              onChange={toggleShowContent}
+            />
+            <Checkbox
+              checked={withArrow}
+              label="With Arrow"
+              onChange={toggleWithArrow}
+            />
+            <Checkbox
+              checked={shouldAlignArrow}
+              label="Align Arrow"
+              onChange={toggleAlignArrow}
+            />
+          </FormFieldGroup>
+        </Flex.Item>
+        <Flex.Item>
+          <View as="div" margin="none" maxWidth="15rem">
+            <SimpleSelect
+              renderLabel="Placement"
+              value={placement}
+              onChange={changePlacement}
+            >
+              {placementsValues.map((placement, index) => (
+                <SimpleSelect.Option
+                  key={index}
+                  id={`${index}`}
+                  value={placement}
+                >
+                  {placement}
+                </SimpleSelect.Option>
+              ))}
+            </SimpleSelect>
+          </View>
+          <View as="div" margin="medium none" maxWidth="15rem">
+            <SimpleSelect
+              value={shadow}
+              onChange={changeShadow}
+              renderLabel="Shadow"
+            >
+              {shadowValues.map((shadow, index) => (
+                <SimpleSelect.Option
+                  key={index}
+                  id={`${index}`}
+                  value={shadow}
+                >
+                  {shadow}
+                </SimpleSelect.Option>
+              ))}
+            </SimpleSelect>
+          </View>
+        </Flex.Item>
+        <Flex.Item align="start">
+          <View as="div" margin="none">
+            <RadioInputGroup
+              name="changeColor"
+              defaultValue="primary"
+              description="Color:"
+              variant="toggle"
+              size="small"
+              onChange={changeColor}
+            >
+              <RadioInput label="Primary" value="primary" />
+              <RadioInput label="Primary inverse" value="primary-inverse" />
+            </RadioInputGroup>
+          </View>
+        </Flex.Item>
+      </Flex>
+      <View as="div" display="block" padding="large" textAlign="center">
+        <Popover
+          renderTrigger={
+            <div
+              style={{
+                display: 'inline-block',
+                height: '3px',
+                width: '3px',
+                background: 'blue'
+              }}
+            />
+          }
+          isShowingContent={isShowingContent}
+          placement={placement}
+          withArrow={withArrow}
+          shouldAlignArrow={shouldAlignArrow}
+          shadow={shadow}
+          color={color}
+        >
+          <Heading>
+            Small
+            <br />
+            Target
+          </Heading>
+        </Popover>
+      </View>
+    </View>
+  )
+}
+
+render(<Example />)
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Consider using a <Link href="/#Tray">Tray</Link> if the content is beyond a mobile screen size</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Put content on the same row as the close "x"</Figure.Item>
+    <Figure.Item>Use with an <Link href="#Overlay">Overlay</Link></Figure.Item>
+    <Figure.Item>Have multiple Popovers open at the same time</Figure.Item>
+    <Figure.Item>Use in place of a <Link href="/#Tooltip">Tooltip</Link> or <Link href="/#Menu">Menu</Link></Figure.Item>
+  </Figure>
+</Guidelines>
+```
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>Keyboard focus must be set in the popover when it appears; usually on the first interactive element</Figure.Item>
+    <Figure.Item>Popovers must contain keyboard focus until they’re closed. This is to ensure that keyboard or screen reader users won't mistakenly interact with background content that is meant to be hidden or inaccessible</Figure.Item>
+    <Figure.Item>When a user closes the Popover, focus must return to a logical place within the page. This is usually the element that triggered opening the popover</Figure.Item>
+    <Figure.Item>Popovers should be able to be closed by clicking away, esc key and/or a close button</Figure.Item>
+  </Figure>
+</Guidelines>
+```