From 653341a69d93c7e4aaf09e601962bca50aec0967 Mon Sep 17 00:00:00 2001
From: mollykreis <20542556+mollykreis@users.noreply.github.com>
Date: Wed, 4 May 2022 16:17:55 -0500
Subject: [PATCH] Anchored region (#530)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# Pull Request

## 🤨 Rationale

Create nimble-anchored-region component.

## 👩‍💻 Implementation

Created a light-weight wrapper around the FAST anchored-region.

## 🧪 Testing

- Added unit tests for the nimble-anchored-region being returned from `tagFor(FoundationAnchoredRegion)` and the element being able to be constructed
- Added matrix tests for the component
    - Note: for technical reasons and because nothing in the anchored region is theme aware, I did not create matrix stories for each theme
- Added storybook story for the component

## ✅ Checklist

- [x] I have updated the project documentation to reflect my changes or determined no changes are needed.
---
 ...-a650c15e-7523-460b-8665-4402c06017d5.json |   7 ++
 .../nimble-components/src/all-components.ts   |   1 +
 .../src/anchored-region/index.ts              |  36 ++++++
 .../src/anchored-region/styles.ts             |   9 ++
 .../tests/anchored-region-matrix.stories.ts   | 104 ++++++++++++++++++
 .../tests/anchored-region.spec.ts             |  19 ++++
 .../tests/anchored-region.stories.ts          | 102 +++++++++++++++++
 7 files changed, 278 insertions(+)
 create mode 100644 change/@ni-nimble-components-a650c15e-7523-460b-8665-4402c06017d5.json
 create mode 100644 packages/nimble-components/src/anchored-region/index.ts
 create mode 100644 packages/nimble-components/src/anchored-region/styles.ts
 create mode 100644 packages/nimble-components/src/anchored-region/tests/anchored-region-matrix.stories.ts
 create mode 100644 packages/nimble-components/src/anchored-region/tests/anchored-region.spec.ts
 create mode 100644 packages/nimble-components/src/anchored-region/tests/anchored-region.stories.ts

diff --git a/change/@ni-nimble-components-a650c15e-7523-460b-8665-4402c06017d5.json b/change/@ni-nimble-components-a650c15e-7523-460b-8665-4402c06017d5.json
new file mode 100644
index 0000000000..dae1734542
--- /dev/null
+++ b/change/@ni-nimble-components-a650c15e-7523-460b-8665-4402c06017d5.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Create nimble-anchored-region",
+  "packageName": "@ni/nimble-components",
+  "email": "20542556+mollykreis@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/nimble-components/src/all-components.ts b/packages/nimble-components/src/all-components.ts
index ebff0bedda..32f664282d 100644
--- a/packages/nimble-components/src/all-components.ts
+++ b/packages/nimble-components/src/all-components.ts
@@ -4,6 +4,7 @@
  * that are required instead of leveraging this file.
  */
 
+import './anchored-region';
 import './breadcrumb';
 import './breadcrumb-item';
 import './button';
diff --git a/packages/nimble-components/src/anchored-region/index.ts b/packages/nimble-components/src/anchored-region/index.ts
new file mode 100644
index 0000000000..ae3ba1add3
--- /dev/null
+++ b/packages/nimble-components/src/anchored-region/index.ts
@@ -0,0 +1,36 @@
+import {
+    DesignSystem,
+    AnchoredRegion as FoundationAnchoredRegion,
+    anchoredRegionTemplate as template
+} from '@microsoft/fast-foundation';
+import { styles } from './styles';
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'nimble-anchored-region': AnchoredRegion;
+    }
+}
+
+// When the anchor element changes position on the page, it is the client's responsibility to update the position
+// of the anchored region by calling update() on the anchored region.
+//
+// When the anchor element is recreated on the page, it is the client's responsibility to reset the reference the
+// anchored region has to the anchor element. This can be done by either recreating the anchor element with a new
+// ID that is also set as the \`anchor\` attribute on the anchored region or by explicitly setting the value of
+// anchorElement on the anchored region to the new anchor element.
+
+/**
+ * A nimble-styled anchored region control.
+ */
+export class AnchoredRegion extends FoundationAnchoredRegion {}
+
+const nimbleAnchoredRegion = AnchoredRegion.compose({
+    baseName: 'anchored-region',
+    baseClass: FoundationAnchoredRegion,
+    template,
+    styles
+});
+
+DesignSystem.getOrCreate()
+    .withPrefix('nimble')
+    .register(nimbleAnchoredRegion());
diff --git a/packages/nimble-components/src/anchored-region/styles.ts b/packages/nimble-components/src/anchored-region/styles.ts
new file mode 100644
index 0000000000..03e6e40024
--- /dev/null
+++ b/packages/nimble-components/src/anchored-region/styles.ts
@@ -0,0 +1,9 @@
+import { css } from '@microsoft/fast-element';
+
+export const styles = css`
+    :host {
+        contain: layout;
+        display: block;
+        z-index: 1000;
+    }
+`;
diff --git a/packages/nimble-components/src/anchored-region/tests/anchored-region-matrix.stories.ts b/packages/nimble-components/src/anchored-region/tests/anchored-region-matrix.stories.ts
new file mode 100644
index 0000000000..5495c25548
--- /dev/null
+++ b/packages/nimble-components/src/anchored-region/tests/anchored-region-matrix.stories.ts
@@ -0,0 +1,104 @@
+import type { Meta, Story } from '@storybook/html';
+import { html, ViewTemplate } from '@microsoft/fast-element';
+import {
+    createMatrix,
+    sharedMatrixParameters
+} from '../../utilities/tests/matrix';
+import { createStory } from '../../utilities/tests/storybook';
+import { hiddenWrapper } from '../../utilities/tests/hidden';
+import '../../all-components';
+import {
+    bodyFont,
+    bodyFontColor,
+    borderHoverColor,
+    applicationBackgroundColor
+} from '../../theme-provider/design-tokens';
+
+const metadata: Meta = {
+    title: 'Tests/Anchored Region',
+    parameters: {
+        ...sharedMatrixParameters()
+    }
+};
+
+export default metadata;
+
+const horizontalPositionStates = [
+    ['Start', 'start'],
+    ['End', 'end'],
+    ['Left', 'left'],
+    ['Right', 'right'],
+    ['Center', 'center']
+] as const;
+type HorizontalPositionState = typeof horizontalPositionStates[number];
+
+const verticalPositionStates = [
+    ['Top', 'top'],
+    ['Bottom', 'bottom'],
+    ['Center', 'center']
+] as const;
+type VerticalPositionState = typeof verticalPositionStates[number];
+
+const component = (
+    [horizontalPositionName, horizontalPosition]: HorizontalPositionState,
+    [verticalPositionName, verticalPosition]: VerticalPositionState
+): ViewTemplate => html`<style>
+        .container {
+            display: inline-flex;
+            margin: 55px;
+            height: 75px;
+            width: 75px;
+        }
+
+        .anchor {
+            top: 25px;
+            left: 25px;
+            width: 75px;
+            height: 75px;
+            font: var(${bodyFont.cssCustomProperty});
+            color: var(${bodyFontColor.cssCustomProperty});
+            border: 1px solid var(${borderHoverColor.cssCustomProperty});
+            background: var(${applicationBackgroundColor.cssCustomProperty});
+        }
+
+        .anchoredRegion {
+            width: 50px;
+            height: 50px;
+            font: var(${bodyFont.cssCustomProperty});
+            color: var(${bodyFontColor.cssCustomProperty});
+            border: 1px solid var(${borderHoverColor.cssCustomProperty});
+            background: var(${applicationBackgroundColor.cssCustomProperty});
+        }
+    </style>
+    <div class="container">
+        <div
+            id="${() => `${verticalPosition}_${horizontalPosition}`}"
+            class="anchor"
+        >
+            Anchor element
+        </div>
+        <nimble-anchored-region
+            anchor="${() => `${verticalPosition}_${horizontalPosition}`}"
+            fixed-placement="true"
+            auto-update-mode="auto"
+            vertical-default-position="${() => verticalPosition}"
+            vertical-positioning-mode="locktodefault"
+            horizontal-default-position="${() => horizontalPosition}"
+            horizontal-positioning-mode="locktodefault"
+        >
+            <div class="anchoredRegion">
+                ${horizontalPositionName} ${verticalPositionName}
+            </div>
+        </nimble-anchored-region>
+        <div></div>
+    </div>`;
+
+export const anchoredRegionThemeMatrix: Story = createStory(
+    createMatrix(component, [horizontalPositionStates, verticalPositionStates])
+);
+
+export const hiddenAnchoredRegion: Story = createStory(
+    hiddenWrapper(
+        html`<nimble-anchored-region hidden>Hidden Anchored Region</nimble-anchored-regionx>`
+    )
+);
diff --git a/packages/nimble-components/src/anchored-region/tests/anchored-region.spec.ts b/packages/nimble-components/src/anchored-region/tests/anchored-region.spec.ts
new file mode 100644
index 0000000000..1ddec45dab
--- /dev/null
+++ b/packages/nimble-components/src/anchored-region/tests/anchored-region.spec.ts
@@ -0,0 +1,19 @@
+import {
+    DesignSystem,
+    AnchoredRegion as FoundationAnchoredRegion
+} from '@microsoft/fast-foundation';
+import { AnchoredRegion } from '..';
+
+describe('Anchored Region', () => {
+    it('should have its tag returned by tagFor(FoundationAnchoredRegion)', () => {
+        expect(DesignSystem.tagFor(FoundationAnchoredRegion)).toBe(
+            'nimble-anchored-region'
+        );
+    });
+
+    it('can construct an element instance', () => {
+        expect(document.createElement('nimble-anchored-region')).toBeInstanceOf(
+            AnchoredRegion
+        );
+    });
+});
diff --git a/packages/nimble-components/src/anchored-region/tests/anchored-region.stories.ts b/packages/nimble-components/src/anchored-region/tests/anchored-region.stories.ts
new file mode 100644
index 0000000000..03ba30716d
--- /dev/null
+++ b/packages/nimble-components/src/anchored-region/tests/anchored-region.stories.ts
@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from '@storybook/html';
+import { html } from '@microsoft/fast-element';
+import { createUserSelectedThemeStory } from '../../utilities/tests/storybook';
+import '../../all-components';
+import {
+    applicationBackgroundColor,
+    bodyFont,
+    bodyFontColor,
+    borderHoverColor
+} from '../../theme-provider/design-tokens';
+
+interface AnchoredRegionArgs {
+    horizontalPosition: string;
+    verticalPosition: string;
+}
+
+const overviewText = `The anchored region should not generally be used directly by nimble clients. Instead, it is intended to be used within other nimble
+components where one part of the component needs to be dynamically positioned based on another element within the component. For example, the popup menu
+within a menu button or a tooltip.
+
+An anchored region is a container component which enables authors to create layouts where the contents of the anchored region can be positioned relative
+to another "anchor" element. Additionally, the anchored region can react to the available space between the anchor and a parent
+["viewport"](https://developer.mozilla.org/en-US/docs/Glossary/viewport) element such that the region is placed on the side of the anchor with the most
+available space, or even resize itself based on that space.`;
+
+const metadata: Meta<AnchoredRegionArgs> = {
+    title: 'Tests/Anchored Region',
+    parameters: {
+        docs: {
+            description: {
+                component: overviewText
+            }
+        }
+    },
+    // prettier-ignore
+    render: createUserSelectedThemeStory(html<AnchoredRegionArgs>`
+        <style>
+            .container {
+                height: 300px;
+            }
+
+            .anchor {
+                position: absolute;
+                top: 100px;
+                left: 300px;
+                width: 150px;
+                height: 150px;
+                font: var(${bodyFont.cssCustomProperty});
+                color: var(${bodyFontColor.cssCustomProperty});
+                border: 2px solid var(${borderHoverColor.cssCustomProperty});
+                background: var(${applicationBackgroundColor.cssCustomProperty});
+            }
+
+            .anchoredRegion {
+                width: 75px;
+                height: 75px;
+                font: var(${bodyFont.cssCustomProperty});
+                color: var(${bodyFontColor.cssCustomProperty});
+                border: 2px solid var(${borderHoverColor.cssCustomProperty});
+                background: var(${applicationBackgroundColor.cssCustomProperty});
+            }
+        </style>
+        <div class="container">
+            <div id="${x => `${x.verticalPosition}_${x.horizontalPosition}`}" class="anchor">
+                Anchor element
+            </div>
+            <nimble-anchored-region
+                anchor="${x => `${x.verticalPosition}_${x.horizontalPosition}`}"
+                fixed-placement="true"
+                auto-update-mode="auto"
+                vertical-default-position="${x => x.verticalPosition}"
+                vertical-positioning-mode="${x => (x.verticalPosition === 'unset' ? 'dynamic' : 'locktodefault')}"
+                horizontal-default-position="${x => x.horizontalPosition}"
+                horizontal-positioning-mode="${x => (x.horizontalPosition === 'unset' ? 'dynamic' : 'locktodefault')}"
+            >
+                <div class="anchoredRegion">
+                    Anchored region
+                </div>
+            </nimble-anchored-region>
+        </div>
+    `),
+    argTypes: {
+        horizontalPosition: {
+            options: ['start', 'end', 'left', 'right', 'center', 'unset'],
+            control: { type: 'select' }
+        },
+        verticalPosition: {
+            options: ['top', 'bottom', 'center', 'unset'],
+            control: { type: 'select' }
+        }
+    },
+    args: {}
+};
+
+export default metadata;
+
+export const anchoredRegion: StoryObj<AnchoredRegionArgs> = {
+    args: {
+        horizontalPosition: 'start',
+        verticalPosition: 'top'
+    }
+};