feat(contextual-help): add contextual help pattern

packages/contextual-help/.npmignore

@@ -0,0 +1,2 @@
+stories
+test

packages/contextual-help/README.md

@@ -0,0 +1,81 @@
+## Description
+
+A `sp-contextual-help` shows a user extra information about the state of either an adjacent component or an entire view. It explains a high-level topic about an experience and can point users to more information elsewhere.
+
+### Usage
+
+[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/contextual-help?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/contextual-help)
+[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/contextual-help?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/contextual-help)
+
+```
+yarn add @spectrum-web-components/contextual-help
+```
+
+Import the side effectful registration of `<sp-contextual-help>` via:
+
+```
+import '@spectrum-web-components/contextual-help/sp-contextual-help.js';
+```
+
+When looking to leverage the `ContextualHelp` base class as a type and/or for extension purposes, do so via:
+
+```
+import { ContextualHelp } from '@spectrum-web-components/contextual-help';
+```
+
+## Example
+
+```html
+<sp-contextual-help headline="Permission required">
+    Your admin must grant you permission before you can create a segment.
+    <sp-link
+        slot="link"
+        href="https://opensource.adobe.com/spectrum-web-components/"
+    >
+        Request permission
+    </sp-link>
+</sp-contextual-help>
+```
+
+## Help
+
+Use `variant="help"` for helpful content: more detailed, in-depth guidance about a task, UI element, tool, or keyboard shortcuts. This may include an image, video, or link and should be helpful in tone.
+
+```html
+<sp-contextual-help headline="What is a segment?" variant="help">
+    Segments identify who your visitors are, what devices and services they use,
+    where they navigate from, and much more.
+    <sp-link
+        slot="link"
+        href="https://opensource.adobe.com/spectrum-web-components/"
+    >
+        Learn more about segments
+    </sp-link>
+</sp-contextual-help>
+```
+
+## Placement
+
+By default a `sp-contextual-help` will render its popover at the `bottom-start` position. This can be customized using the `placement` attribute and supports [all the placement options](http://localhost:8000/components/overlay-trigger/#placement) an `overlay-trigger` component supports.
+
+```html
+<sp-contextual-help headline="Permission required" placement="top-start">
+    Your admin must grant you permission before you can create a segment.
+    <sp-link
+        slot="link"
+        href="https://opensource.adobe.com/spectrum-web-components/"
+    >
+        Request permission
+    </sp-link>
+</sp-contextual-help>
+```
+
+## Events
+
+`sp-contextual-help` does not fire any events of its own. You can listen, however, for the `sp-open` and `sp-closed` events which are fired when the popover opens or closes.
+
+## Accessibility
+
+Given that the trigger is an icon-only `sp-action-button`, it is important to provide an accessible name for it, so that it can be properly announced by screen readers.
+By default, the `sp-contextual-help` uses an `aria-label` property with either "Informations" or "Help" as values, depending on the component's `variant`.
+You can customize this using the `label` attribute.

packages/contextual-help/exports.json

@@ -0,0 +1,4 @@
+{
+    "./src/*": "./src/*.js",
+    "./sp-contextual-help.js": "./sp-contextual-help.js"
+}

packages/contextual-help/package.json

@@ -0,0 +1,77 @@
+{
+    "name": "@spectrum-web-components/contextual-help",
+    "version": "0.0.1",
+    "publishConfig": {
+        "access": "public"
+    },
+    "description": "Web component implementation of a Spectrum design ContextualHelp",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/adobe/spectrum-web-components.git",
+        "directory": "packages/contextual-help"
+    },
+    "author": "",
+    "homepage": "https://adobe.github.io/spectrum-web-components/components/contextual-help",
+    "bugs": {
+        "url": "https://github.com/adobe/spectrum-web-components/issues"
+    },
+    "main": "src/index.js",
+    "module": "src/index.js",
+    "type": "module",
+    "exports": {
+        ".": {
+            "development": "./src/index.dev.js",
+            "default": "./src/index.js"
+        },
+        "./package.json": "./package.json",
+        "./src/ContextualHelp.js": {
+            "development": "./src/ContextualHelp.dev.js",
+            "default": "./src/ContextualHelp.js"
+        },
+        "./src/contextual-help.css.js": "./src/contextual-help.css.js",
+        "./src/index.js": {
+            "development": "./src/index.dev.js",
+            "default": "./src/index.js"
+        },
+        "./sp-contextual-help.js": {
+            "development": "./sp-contextual-help.dev.js",
+            "default": "./sp-contextual-help.js"
+        }
+    },
+    "scripts": {
+        "test": "echo \"Error: run tests from mono-repo root.\" && exit 1"
+    },
+    "files": [
+        "**/*.d.ts",
+        "**/*.js",
+        "**/*.js.map",
+        "custom-elements.json",
+        "!stories/",
+        "!test/"
+    ],
+    "keywords": [
+        "spectrum css",
+        "web components",
+        "lit-element",
+        "lit-html"
+    ],
+    "dependencies": {
+        "@spectrum-web-components/action-button": "^0.42.2",
+        "@spectrum-web-components/base": "^0.42.2",
+        "@spectrum-web-components/dialog": "^0.42.2",
+        "@spectrum-web-components/icons-workflow": "^0.42.2",
+        "@spectrum-web-components/overlay": "^0.42.2",
+        "@spectrum-web-components/popover": "^0.42.2"
+    },
+    "devDependencies": {
+        "@spectrum-css/contextualhelp": "^2.1.5"
+    },
+    "types": "./src/index.d.ts",
+    "customElements": "custom-elements.json",
+    "sideEffects": [
+        "./sp-*.js",
+        "./**/*.dev.js",
+        "./**/*.dev.js"
+    ]
+}

packages/contextual-help/sp-contextual-help.ts

@@ -0,0 +1,20 @@
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import { ContextualHelp } from './src/ContextualHelp.js';
+
+customElements.define('sp-contextual-help', ContextualHelp);
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'sp-contextual-help': ContextualHelp;
+    }
+}

packages/contextual-help/src/ContextualHelp.ts

@@ -0,0 +1,205 @@
+/*
+Copyright 2024 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import {
+    CSSResultArray,
+    html,
+    render,
+    SpectrumElement,
+    TemplateResult,
+} from '@spectrum-web-components/base';
+import '@spectrum-web-components/action-button/sp-action-button.js';
+import '@spectrum-web-components/overlay/sp-overlay.js';
+import '@spectrum-web-components/icons-workflow/icons/sp-icon-help-outline.js';
+import '@spectrum-web-components/icons-workflow/icons/sp-icon-info-outline.js';
+import { ifDefined } from '@spectrum-web-components/base/src/directives.js';
+import {
+    property,
+    state,
+} from '@spectrum-web-components/base/src/decorators.js';
+import {
+    removeSlottableRequest,
+    SlottableRequestEvent,
+} from '@spectrum-web-components/overlay/src/slottable-request-event.js';
+import type { Placement } from '@spectrum-web-components/overlay/src/overlay-types.js';
+import {
+    IS_MOBILE,
+    MatchMediaController,
+} from '@spectrum-web-components/reactive-controllers/src/MatchMedia.js';
+
+import styles from './contextual-help.css.js';
+
+/**
+ * Spectrum Contextual help provides additional information about
+ * the state of either an adjacent component or an entire view.
+ * @element sp-contextual-help
+ *
+ * @slot Text content to display in the popover
+ * @slot link - link to additional informations
+ */
+export class ContextualHelp extends SpectrumElement {
+    protected isMobile = new MatchMediaController(this, IS_MOBILE);
+
+    public static override get styles(): CSSResultArray {
+        return [styles];
+    }
+
+    /**
+     * Optional title to be displayed inside the popover.
+     * @param {String} headline
+     */
+    @property()
+    public headline?: string;
+
+    /**
+     * Provides an accessible name for the action button trigger.
+     * @param {String} label
+     */
+    @property()
+    public label?: string;
+
+    /**
+     * The `variant` property applies specific styling on the action button trigger.
+     * @param {String} variant
+     */
+    @property()
+    public variant: 'info' | 'help' = 'info';
+
+    /**
+     * @type {"top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end"}
+     * @attr
+     */
+    @property({ reflect: true })
+    public placement?: Placement = 'bottom-start';
+
+    /**
+     * The `offset` property accepts either a single number, to
+     * define the offset of the Popover along the main axis from
+     * the action button, or 2-tuple, to define the offset along the
+     * main axis and the cross axis.
+     */
+    @property({ type: Number })
+    public offset: number | [number, number] = 0;
+
+    @state()
+    overlayOpen = false;
+
+    private get buttonAriaLabel(): string {
+        if (this.label) {
+            return this.label;
+        } else {
+            if (this.variant === 'help') {
+                return 'Help';
+            }
+            return 'Informations';
+        }
+    }
+
+    private renderPopover(event: SlottableRequestEvent): void {
+        event.stopPropagation();
+
+        if (event.data === removeSlottableRequest) {
+            render(undefined, event.target as HTMLElement);
+            return;
+        }
+
+        import('@spectrum-web-components/popover/sp-popover.js');
+
+        const template = html`
+            <sp-popover class="popover">
+                <section>
+                    ${this.headline &&
+                    html`
+                        <h2 class="heading">${this.headline}</h2>
+                    `}
+                    <slot></slot>
+                    <div class="link">
+                        <slot name="link"></slot>
+                    </div>
+                </section>
+            </sp-popover>
+        `;
+
+        render(template, event.target as HTMLElement);
+    }
+
+    private renderDialog(event: SlottableRequestEvent): void {
+        event.stopPropagation();
+
+        if (event.data === removeSlottableRequest) {
+            render(undefined, event.target as HTMLElement);
+            return;
+        }
+
+        import('@spectrum-web-components/dialog/sp-dialog-wrapper.js');
+        const headlineVisibility = !this.headline ? 'none' : undefined;
+
+        const template = html`
+            <sp-dialog-wrapper
+                dismissable
+                underlay
+                headline=${ifDefined(this.headline)}
+                headline-visibility=${ifDefined(headlineVisibility)}
+            >
+                <slot></slot>
+                <div class="link">
+                    <slot name="link"></slot>
+                </div>
+            </sp-dialog-wrapper>
+        `;
+
+        render(template, event.target as HTMLElement);
+    }
+
+    protected override render(): TemplateResult {
+        const actualPlacement = this.isMobile.matches
+            ? undefined
+            : this.placement;
+
+        return html`
+            <sp-action-button
+                quiet
+                size="s"
+                id="trigger"
+                aria-label=${this.buttonAriaLabel}
+                ?is-active=${this.overlayOpen}
+            >
+                ${this.variant === 'help'
+                    ? html`
+                          <sp-icon-help-outline
+                              slot="icon"
+                          ></sp-icon-help-outline>
+                      `
+                    : html`
+                          <sp-icon-info-outline
+                              slot="icon"
+                          ></sp-icon-info-outline>
+                      `}
+            </sp-action-button>
+            <sp-overlay
+                trigger="trigger@click"
+                placement=${ifDefined(actualPlacement)}
+                type=${this.isMobile.matches ? 'modal' : 'auto'}
+                receives-focus="true"
+                .offset=${this.offset}
+                @sp-opened=${() => {
+                    this.overlayOpen = true;
+                }}
+                @sp-closed=${() => {
+                    this.overlayOpen = false;
+                }}
+                @slottable-request=${this.isMobile.matches
+                    ? this.renderDialog
+                    : this.renderPopover}
+            ></sp-overlay>
+        `;
+    }
+}