feat(coachmark): rename "sp-coachmark" to "sp-coachmark-indicator", a…

…dd "sp-coachmark" (#3639) * chore: first commit coach indicator * chore: module declaration in type file * chore: coach indicator main files changes * chore: coach indicator token files * chore: updated golden image cache * chore: updated golden image cache * chore: updated golden image cache * chore(coach-indicator): focus ring disabling for reduce motion * chore(coach-indicator): updated golden image cache * chore(coachmark): added config and main src file * chore(coach-indicator): added reduced motion for ring animation * chore(coachmark): readme and storybook update * chore(coachmark): updated readme * test(coachmark): added tests * chore(coachmark): update golden image cache * chore(coachmark): updated images in storybook and readme * chore(coachmark): updated golden image cache * chore(coach-indicator): update tokens version and reduced motion update * chore(coach-indicator): reduced motion css * chore(coach-indicator): updated golden image cache * chore(coachmark): updated button group mobile and desktop view * chore(coachmark): updated heading content * chore(coachmark): added aria-label to sp-button with icon * chore(coachmark): update action menu logic * chore(coach-indicator): updated golden image cache * chore(coachmark): updated storybook and readme * chore(coachmark): added coach indicator inside coachmark * chore(coachmark): updated storybook and readme * chore(coachmark): updated golden image cache * chore(coachmark): updated tests * chore(coachmark): bump version of dependecies * chore(coachmark): updated to add new additional features * chore(coachmark): unit tests * chore(coachmark): update coachmarkitem reference * chore(coachmark): updated storybook * chore(coachmark): updated readme * chore(coachmark): updated readme * chore(coachmark): updated storybook * chore(coachmark): updated golden image cache * chore(coachmark): updated tests * chore(coachmark): updated storybook for gif * chore: updated readme * chore: updated golden images cache * chore(coachmark): added tests * chore(coachmark): shortcut render * chore(coachmark): updated readme * chore: updated golden image cache * chore(coachmark): update basic test * chore: reverting button and button group changes * chore: reverting button css * chore: reverting button css * chore(coachmark): removed video and adjusted keys css * chore(coachmark): removed video and adjusted keys css in coachmark trigger storybook * chore(coachmark): removed trigger and update api to use only one component with slot * chore(coachmark): updated readme * chore(coachmark): removed coachmark trigger readme * chore(coachmark): updated tests * chore(coachmark): added button css compiled * chore: test analyze * chore: test analyze revert * chore(coachmark): temp fix for 16:9 image container * chore(coachmark): update golden image cache * chore(coachmark): updated tests * chore(coachmark): coachmark cleanup * chore(coachmark): updated coachmark trigger to coachmark and coachmark to coachmarkpopover * chore(coachmark): comment updated on coachmark popover * chore(coachmark): code coverage fix * chore: updated golden image cache * chore(coachmark): updated readme * chore(coachmark): updated storybook with action buttons * chore(coachmark): updated readme to include modifer keys * chore(coachmark): updated golden image cache * chore(coachmark): updated tests * chore(coachmark): updated tests * chore(coachmark): storybook fix * chore(coachmark): updated golden image cache * chore(coachmark): removed unused code * chore(coachmark): disabled focus on trigger * chore(coachmark): updated golden image cache * chore(coachmark): updated css versions * chore(coachmark): updated golden images cache * chore(coachmark): updated golden images cache * chore(coachmark): updated golden images cache * chore(coachmark): added static variants to coach indicator * chore(coachmark): updated golden image cache * chore(coachmark): removed coachmark popover underlay wrapper * chore(coachmark): updated readme for coachmark * chore(coachmark): updated golden image cache * chore(coachmark): updated README * chore(coachmark): revert button css * chore(coachmark): updated coachmark css depedency * chore(coachmark): updated step readability * chore: removing lit-html pragma in documentation * chore(coachmark): update yarn.lock * chore(coachmark): code cleanup * chore(coachmark): update golden image cache * chore(coachmark): updated storybook * chore(coachmark): updated storybook and tests * chore(coachmark): updated golden image cache * chore(coachmark): updated function declaration to anonymouse function for performance boost * chore(coachmark): updated golden image cache * chore(coachmark): updated golden image cache * chore(coachmark): updated golden image cache * chore(coachmark): updated stories * chore(coachmark): updated golden image cache * chore(coachmark): updated golden image cache * chore(coachmark): updated golden image cache * chore(coachmark): updated golden image cache * chore(coachmark): removing redundant code * chore(coachmark): updated docs and alias tokens to use core tokens * chore(coachmark): updated core token * chore(coachmark): updated core tokens * chore(coachmark): updated golden image cache * chore(coachmark): updated coachmark css * chore(coachmark): updated golden image cache * chore(coachmark): updated coach indicator fix with stub css * chore(coachmark): updated golden image cache * chore(coachmark): updated readme on coach-indicator * chore(coachmark): updated readme on coach-indicator file reference * chore(coachmark): updated golden image cache --------- Co-authored-by: Rajdeep Chandra <rajdeepc@adobe.com> Co-authored-by: Rajdeep Chandra <rajdeepchandra@Rajdeeps-MacBook-Pro-2.local> Co-authored-by: Rajdeep Chandra <rajdeepchandra@rajdeeps-mbp-2.macromedia.com>
adobe · Feb 8, 2024 · a94389c · a94389c
1 parent 80d2228
commit a94389c
Show file tree

Hide file tree

Showing 26 changed files with 1,942 additions and 279 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -10,7 +10,7 @@ executors:
 parameters:
     current_golden_images_hash:
         type: string
-        default: f0b23861090807cce5d78a70ed43391f367dc3dc
+        default: 6467e2788b3f7a0c9e1f9b836f54adee89074e9d
     wireit_cache_name:
         type: string
         default: wireit

diff --git a/packages/coachmark/README.md b/packages/coachmark/README.md
@@ -1,6 +1,6 @@
 ## Description
 
-An `<sp-coachmark>` element can be used to bring added attention to specific parts of your page.
+`<sp-coachmark>` is a temporary message that educates users through new or unfamiliar product experiences. They can be chained into a sequence to form a tour.
 
 ### Usage
 
@@ -16,6 +16,7 @@ Import the side effectful registration of `<sp-coachmark>` via:
 
 ```
 import '@spectrum-web-components/coachmark/sp-coachmark.js';
+
 ```
 
 When looking to leverage the `Coachmark` base class as a type and/or for extension purposes, do so via:
@@ -24,18 +25,201 @@ When looking to leverage the `Coachmark` base class as a type and/or for extensi
 import { Coachmark } from '@spectrum-web-components/coachmark';
 ```
 
-## Standard
+## Example
+
+## Default
+
+Coachmark can take a `placement` and an `offset` similar to the [Overlay](https://opensource.adobe.com/spectrum-web-components/components/overlay/).
 
 ```html
-<sp-coachmark></sp-coachmark>
-<sp-coachmark variant="dark"></sp-coachmark>
-<sp-coachmark variant="light"></sp-coachmark>
+<sp-coachmark open>
+    <div slot="title">Coachmark with Text Only</div>
+    <div slot="content">
+        This is a Coachmark with nothing but text in it. Kind of lonely in here.
+    </div>
+</sp-coachmark>
 ```
 
-## Quiet
+## Using Action Menu
+
+Coach marks can include an `<sp-action-menu>`, which appears at the top right of the coach mark. The `<sp-action-menu>` should only include ways to interact with the coach mark tour as a whole, with options like “Skip tour” or “Restart tour.”
 
 ```html
-<sp-coachmark quiet></sp-coachmark>
-<sp-coachmark quiet variant="dark"></sp-coachmark>
-<sp-coachmark quiet variant="light"></sp-coachmark>
+<sp-coachmark
+    open
+    current-step="2"
+    total-steps="8"
+    primary-cta="Next"
+    secondary-cta="Previous"
+>
+    <div slot="title">Coachmark with Text Only</div>
+    <div slot="content">
+        This is a Coachmark with nothing but text in it. Kind of lonely in here.
+    </div>
+    <sp-action-menu placement="bottom-end" quiet slot="actions">
+        <sp-menu-item>Skip tour</sp-menu-item>
+        <sp-menu-item>Restart tour</sp-menu-item>
+    </sp-action-menu>
+</sp-coachmark>
+```
+
+## User Action Dependent
+
+User action-dependent coachmarks are designed to guide users based on their interactions within your application. In such cases, there is no "Next Step" button, as the coachmark progresses when the user takes a specific action. This allows users to learn by doing, rather than simply reading instructions. The coachmark remains until the user performs the required action or takes an alternative route in the tour, such as skipping, restarting, or moving back to a previous step.
+
+Inside the `<sp-coachmark>`, add the content and instructions for the coachmark in the `<sp-coachmark>`. You can also define primary and secondary CTA buttons for user interaction.
+
+**Event Handling:**
+
+The primary and secondary CTA buttons within the coachmark popover can be configured to dispatch events when clicked.
+
+```html-live
+<sp-coachmark
+    id="coachmark-action"
+    open
+    current-step="2"
+    total-steps="8"
+    primary-cta="Asset added"
+    secondary-cta="Previous"
+>
+    <div slot="title">Coachmark with user action</div>
+    <div slot="content">
+        This is a Coachmark with nothing but text in it. Kind of lonely in here.
+    </div>
+    <sp-action-menu placement="bottom-end" quiet slot="actions">
+        <sp-menu-item>Skip tour</sp-menu-item>
+        <sp-menu-item>Restart tour</sp-menu-item>
+    </sp-action-menu>
+</sp-coachmark>
+<script type="module">
+    const initCoachMark = () => {
+        const coachmark = document.querySelector('#coachmark-action');
+        coachmark.addEventListener('primary', () => console.log('primary call to action'));
+        coachmark.addEventListener('secondary', () => console.log('secondary call to action'));
+
+    };
+    customElements.whenDefined('sp-coachmark').then(() => {
+                initCoachMark();
+    });
+</script>
 ```
+
+<script type="module">
+    const initCoachMark = () => {
+        const coachmark = document.querySelector('#coachmark-action');
+        coachmark.addEventListener('primary', () => console.log('primary call to action'));
+        coachmark.addEventListener('secondary', () => console.log('secondary call to action'));
+    };
+    customElements.whenDefined('sp-coachmark').then(() => {
+                initCoachMark();
+    });
+</script>
+
+## Using Images, GIFs
+
+Coach marks can contain images or videos that relate to their content, such as demonstrations of gestures, the feature being used, or illustrations.
+To use these kinds of media in your rich tooltip, specify a `src`, the type of media, either by using the string or `media-type` object, and
+an optional `imageAlt` text describing the content.
+
+Media Types allowed: `Images & Gifs`
+
+### Image
+
+```html
+<sp-coachmark
+    current-step="2"
+    total-steps="8"
+    open
+    primary-cta="Next"
+    secondary-cta="Previous"
+    src="https://picsum.photos/id/237/200/300"
+    media-type="image"
+>
+    <div slot="title">Coachmark with 16:9 image</div>
+    <div slot="content">This is a Coachmark with some description</div>
+    <sp-action-menu placement="bottom-end" quiet slot="actions">
+        <sp-menu-item>Skip tour</sp-menu-item>
+        <sp-menu-item>Restart tour</sp-menu-item>
+    </sp-action-menu>
+</sp-coachmark>
+```
+
+### Custom Image/Gif
+
+A custom media can also be added via `<slot name="cover-photo"></slot>`
+
+```html
+<sp-coachmark
+    current-step="2"
+    total-steps="8"
+    open
+    primary-cta="Next"
+    secondary-cta="Previous"
+>
+    <div slot="title">Coachmark with 16:9 image</div>
+    <div slot="content">This is a Coachmark with some description</div>
+    <img slot="asset" src="https://picsum.photos/id/237/200/300" alt="" />
+    <sp-action-menu placement="bottom-end" quiet slot="actions">
+        <sp-menu-item>Skip tour</sp-menu-item>
+        <sp-menu-item>Restart tour</sp-menu-item>
+    </sp-action-menu>
+</sp-coachmark>
+```
+
+## Shortcut keys and modifier keys
+
+Shortcut keys and modifier keys are ways to show users how to trigger a particular tool.
+
+The `shortcutKey` is the primary key used to trigger an interaction and are typically an alphanumeric value (and thus will be rendered as an uppercase character), while the
+`modifierKeys` are an array of `string`s that represent alternate keys that can be pressed, like `Shift`, `Alt`, `Cmd`, etc.
+
+```html-live
+    <sp-coachmark
+        open
+        current-step="2"
+        total-steps="8"
+        primary-cta="Next"
+        secondary-cta="Previous"
+        id="coachmark-keys"
+    >
+        <sp-action-menu placement="bottom-end" quiet slot="actions">
+            <sp-menu-item>Skip tour</sp-menu-item>
+            <sp-menu-item>Restart tour</sp-menu-item>
+        </sp-action-menu>
+    </sp-coachmark>
+<script type="module">
+    const initCoachMark = () => {
+        const coachmark = document.querySelector('#coachmark-keys');
+        const modifierKeys = ['⇧ Shift', '⌘'];
+        const content = {
+            title: 'I am a Coachmark with keys',
+            description: 'This is a Coachmark with nothing but text in it.'
+        };
+        coachmark.content= content
+        coachmark.modifierKeys = modifierKeys
+    };
+    customElements.whenDefined('code-example').then(() => {
+        customElements.whenDefined('sp-coachmark').then(() => {
+                initCoachMark();
+        });
+    });
+</script>
+```
+
+<script type="module">
+    const initCoachMark = () => {
+        const coachmark = document.querySelector('#coachmark-keys');
+        const modifierKeys = ['⇧ Shift', '⌘'];
+        const content = {
+            title: 'I am a Coachmark with keys',
+            description: 'This is a Coachmark with nothing but text in it.'
+        };
+        coachmark.content= content
+        coachmark.modifierKeys = modifierKeys
+    };
+    customElements.whenDefined('code-example').then(() => {
+        customElements.whenDefined('sp-coachmark').then(() => {
+                initCoachMark();
+        });
+    });
+</script>
diff --git a/packages/coachmark/coach-indicator.md b/packages/coachmark/coach-indicator.md
@@ -0,0 +1,49 @@
+## Description
+
+`<sp-coach-indicator>` show the connection between an object and its explanation in a touring mode — for example, the source of <sp-coachmark> in an onboarding tour.
+
+### Usage
+
+[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/coachmark?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/coachmark)
+[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/coachmark?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/coachmark)
+
+```
+yarn add @spectrum-web-components/coachmark
+```
+
+Import the side effectful registration of `<sp-coach-indicator>` via:
+
+```
+import '@spectrum-web-components/coachmark/sp-coach-indicator.js';
+```
+
+When looking to leverage the `CoachIndicator` base class as a type and/or for extension purposes, do so via:
+
+```
+import { CoachIndicator } from '@spectrum-web-components/coachmark';
+```
+
+## Variants
+
+<sp-tabs selected="standard" auto label="Variant Options">
+<sp-tab value="standard">Standard</sp-tab>
+<sp-tab-panel value="standard">
+
+```html
+<sp-coach-indicator></sp-coach-indicator>
+<sp-coach-indicator variant="dark"></sp-coach-indicator>
+<sp-coach-indicator variant="light"></sp-coach-indicator>
+```
+
+</sp-tab-panel>
+<sp-tab value="quiet">Quiet</sp-tab>
+<sp-tab-panel value="quiet">
+
+```html
+<sp-coach-indicator quiet></sp-coach-indicator>
+<sp-coach-indicator quiet variant="dark"></sp-coach-indicator>
+<sp-coach-indicator quiet variant="light"></sp-coach-indicator>
+```
+
+</sp-tab-panel>
+</sp-tabs>
diff --git a/packages/coachmark/exports.json b/packages/coachmark/exports.json
@@ -1,4 +1,5 @@
 {
     "./src/*": "./src/*",
-    "./sp-coachmark.js": "./sp-coachmark.js"
+    "./sp-coachmark.js": "./sp-coachmark.js",
+    "./sp-coach-indicator.js": "./sp-coach-indicator.js"
 }
diff --git a/packages/coachmark/package.json b/packages/coachmark/package.json
@@ -25,10 +25,19 @@
             "default": "./src/index.js"
         },
         "./package.json": "./package.json",
+        "./src/CoachIndicator.js": {
+            "development": "./src/CoachIndicator.dev.js",
+            "default": "./src/CoachIndicator.js"
+        },
         "./src/Coachmark.js": {
             "development": "./src/Coachmark.dev.js",
             "default": "./src/Coachmark.js"
         },
+        "./src/CoachmarkItem.js": {
+            "development": "./src/CoachmarkItem.dev.js",
+            "default": "./src/CoachmarkItem.js"
+        },
+        "./src/coach-indicator.css.js": "./src/coach-indicator.css.js",
         "./src/coachmark.css.js": "./src/coachmark.css.js",
         "./src/index.js": {
             "development": "./src/index.dev.js",
@@ -37,6 +46,10 @@
         "./sp-coachmark.js": {
             "development": "./sp-coachmark.dev.js",
             "default": "./sp-coachmark.js"
+        },
+        "./sp-coach-indicator.js": {
+            "development": "./sp-coach-indicator.dev.js",
+            "default": "./sp-coach-indicator.js"
         }
     },
     "scripts": {
@@ -57,10 +70,19 @@
         "lit-html"
     ],
     "dependencies": {
-        "@spectrum-web-components/base": "^0.40.5"
+        "@spectrum-web-components/asset": "^0.40.5",
+        "@spectrum-web-components/base": "^0.40.5",
+        "@spectrum-web-components/button": "^0.40.5",
+        "@spectrum-web-components/button-group": "^0.40.5",
+        "@spectrum-web-components/icon": "^0.40.5",
+        "@spectrum-web-components/icons-ui": "^0.40.5",
+        "@spectrum-web-components/quick-actions": "^0.40.5",
+        "@spectrum-web-components/reactive-controllers": "^0.40.5",
+        "@spectrum-web-components/shared": "^0.40.5"
     },
     "devDependencies": {
-        "@spectrum-css/coachmark": "^5.0.75"
+        "@spectrum-css/coachindicator": "1.0.0",
+        "@spectrum-css/coachmark": "6.0.0"
     },
     "types": "./src/index.d.ts",
     "customElements": "custom-elements.json",

diff --git a/packages/coachmark/sp-coach-indicator.ts b/packages/coachmark/sp-coach-indicator.ts
@@ -0,0 +1,21 @@
+/*
+Copyright 2023 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 { CoachIndicator } from './src/CoachIndicator.js';
+
+import { defineElement } from '@spectrum-web-components/base/src/define-element.js';
+defineElement('sp-coach-indicator', CoachIndicator);
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'sp-coach-indicator': CoachIndicator;
+    }
+}