@atlaskit/spotlight 0.0.18 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @atlaskit/spotlight
 
+## 0.1.0
+
+### Minor Changes
+
+- [`0bc8c3d1f15ee`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/0bc8c3d1f15ee) -
+  Apply `flex-direction: row-reverse;` to `SpotlightControls` to make `SpotlightDismissControl` the
+  first focusable element in `Spotlight`.
+
+### Patch Changes
+
+- [`6fa400e1910b7`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/6fa400e1910b7) -
+  Styling update to `PopoverContent` to set `z-index: 800` to ensure `Spotlight` displays correctly
+  on top of Atlassian layering elements.
+- Updated dependencies
+
 ## 0.0.18
 
 ### Patch Changes

package/constellation/index/examples.mdx

@@ -0,0 +1,73 @@
+---
+order: 0
+---
+
+import PlacementsExample from '../../examples/constellation/placements';
+import SingleStepExample from '../../examples/constellation/single-step';
+import MultipleStepsExample from '../../examples/constellation/multiple-steps';
+import MediaExample from '../../examples/constellation/media';
+import ControlsExample from '../../examples/constellation/controls';
+
+## Single Step
+
+Ideally, spotlights should only have a single step so as not to overwhelm users with too much
+information. Try and combine or eliminate tasks where possible. Dismiss functionality is required.
+Don't force users to participate.
+
+To show/hide the `Spotlight`, simply use a `useState` to control the `isVisible` prop on
+`PopoverContent`. To position the `Spotlight`, use `PopoverProvider`, `PopoverTarget` and
+`PopoverContent` and set the
+
+<Example Component={SingleStepExample} packageName="@atlaskit/spinner" />
+
+## Multiple Steps/Tour
+
+Multiple steps should be avoided if possible. Try and combine or eliminate steps where possible. If
+multiple steps are required, preference managing the tour with a `useState`. As a last resort a
+React context may be used. However, these contexts will often need to be wrapping the entire `App`
+and therefore will cause the entire `App` to re-render every time a new spotlight step is shown.
+
+<Example Component={MultipleStepsExample} packageName="@atlaskit/spinner" />
+
+## Placements
+
+Spotlight placements are static — they do not change as the user scrolls, or if the `PopoverContent`
+overflows out of the viewport. Make sure to choose a placement that ensures the `Spotlight` is
+displayed in full.
+
+By design `@atlaskit/spotlight` does not have a blanket, scroll-lock, focus-trap, or click-outside
+to dismiss functionality. This is to ensure the user is not hijacked into the spotlight experience,
+and can opt-in if they are interested.
+
+<Example Component={PlacementsExample} packageName="@atlaskit/spinner" />
+
+## Media
+
+Media is optional for a `Spotlight`. However if it is used it must be 295px width X 135px height.
+This is to ensure correct reflow on smaller viewports.
+
+Media can be an image, video, animation, or any other visual aid to communicate spotlight intent.
+
+<Example Component={MediaExample} packageName="@atlaskit/spinner" />
+
+## Controls
+
+`SpotlightDismissControl` is required for all `Spotlight` components. It **must** be the first
+focusable element on the `Spotlight` card. This means that when defining the controls,
+`SpotlightDismissControl` should appear first in the DOM order:
+
+```tsx
+<SpotlighControls>
+	<SpotlightDismissControl />
+	<SpotlightShowMoreControl />
+</SpotlighControls>
+```
+
+Internally, `SpotlighControls` applies `flex-direction: row-reverse;` so that
+`SpotlightDismissControl` visually displays after `SpotlightShowMoreControl` while maintaining
+correct tabbing order.
+
+`SpotlightShowMoreControl` is optional for `Spotlight` components. It should be used to allow users
+to opt out of a spotlight experience, or understand why they are seeing the spotlight experience.
+
+<Example Component={ControlsExample} packageName="@atlaskit/spinner" />

package/constellation/index/usage.mdx

@@ -0,0 +1,104 @@
+import { SingleStepSpotlightTable, MultiStepSpotlightTable } from '@af/design-system-docs-ui';
+
+## Usage
+
+A spotlight focuses attention on a specific part of the UI, such as a button or icon, to educate
+users about key features or workflows. Spotlights are most effective for onboarding new users,
+driving feature discovery, or highlighting important changes. Use them sparingly — if your UI needs
+frequent spotlights, consider simplifying the core experience instead.
+
+## Spotlight Scenarios
+
+### Top use cases
+
+- **Onboarding new users**: Guide first-time users to essential features and workflows.
+- **Feature discovery**: Help existing users learn about new or updated capabilities.
+
+### Growth use cases
+
+- **Cross-flow, cross-join, co-use**: Use spotlights only when triggered by another message type
+  (e.g., a banner that asks for permission to “show me” before triggering a spotlight).
+
+### Unsupported use cases
+
+- **Transactional**: Never use spotlights for transactional messages.
+
+## Guiding Principles
+
+- **Use sparingly**: Spotlights are a Level 3 (Neutral Plus) attention component. Overuse can
+  distract and fatigue users.
+- **One at a time**: Only show one spotlight at a time.
+- **Dismissibility**: Always provide a dismiss option. Never force participation.
+- **Step count**: Prefer single-step spotlights. For tours, keep flows short (2–3 steps max).
+- **Orchestration**: Build spotlights with Post Office to avoid message collisions and enforce
+  fatigue rules (Atlassians Only).
+- **Media**: Use media (images or video) only when it enhances understanding. Exclude media if the
+  spotlight already focuses attention effectively.
+
+## Anatomy & Specifications
+
+### Single Step Spotlight
+
+<SingleStepSpotlightTable />
+<br />
+
+### Multi Step Spotlight/Tour
+
+<MultiStepSpotlightTable />
+<br />
+
+## Visual Guidance
+
+- **Complexity**: Match the visual complexity to the feature’s learning curve. Use text-only for
+  simple features, a single illustration for moderate complexity, and a narrative/motion for complex
+  flows.
+
+- **Brand color**: Use solid backgrounds to focus attention. Limit to three brand colors per
+  composition.
+
+- **Composition**: Highlight the focal point with size, color, and gesture lines. Use motion only if
+  it clarifies the feature.
+
+## Behavior
+
+- **Entry points**: Spotlights should be triggered contextually and never interrupt core workflows.
+  For cross-product or promotional spotlights, use a less obtrusive entrypoint (like a banner)
+  first.
+
+- **Tours**: Sequence steps logically. Keep flows short and focused.
+
+## Best Practices
+
+- Use spotlights only when necessary to drive understanding or adoption.
+- Sequence multi-step spotlights logically; aim for 2–3 steps max.
+- Always allow users to dismiss or skip.
+- Avoid competing with other in-product messages.
+- Prefer embedded, contextual education over overlays.
+
+## Accessibility
+
+- The headline is used as the accessible name for the spotlight dialog.
+- Keep content concise and avoid motion that could be disruptive.
+- Ensure the carat and spotlight are not truncated by the browser bounds.
+
+## Content Guidelines
+
+## Headline
+
+- Required. Begin with an active verb where possible.
+- Brief and direct; communicate the main benefit.
+- Limit to one line and use sentence case.
+
+## Body
+
+- Required. Briefly elaborate on the intent.
+- Avoid repeating the headline verb.
+- Two lines max. Focus on benefits and relevance.
+- Reference only visible elements.
+
+## CTA
+
+- Required. One clear next action.
+- Avoid plan or feature names in CTAs.
+- For tours: “Next”, “Back”, “Done”.
+- For features: 1–3 words; “Done” is acceptable if no clear next action.

package/dist/cjs/ui/controls/index.compiled.css

@@ -0,0 +1,3 @@
+
+._zulpu2gc{gap:var(--ds-space-100,8px)}._1e0c1txw{display:flex}
+._2lx21sbv{flex-direction:row-reverse}

package/dist/cjs/ui/controls/index.js

@@ -1,3 +1,4 @@
+/* index.tsx generated by @compiled/babel-plugin v0.36.1 */
 "use strict";
 
 var _typeof = require("@babel/runtime/helpers/typeof");
@@ -5,9 +6,14 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.SpotlightControls = void 0;
+require("./index.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
-var _compiled = require("@atlaskit/primitives/compiled");
+var React = _react;
+var _runtime = require("@compiled/react/runtime");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
+var styles = {
+  root: "_zulpu2gc _1e0c1txw _2lx21sbv"
+};
 /**
  * __Spotlight controls__
  *
@@ -16,10 +22,10 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
 var SpotlightControls = exports.SpotlightControls = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {
   var testId = _ref.testId,
     children = _ref.children;
-  return /*#__PURE__*/_react.default.createElement(_compiled.Flex, {
-    testId: testId,
+  return /*#__PURE__*/React.createElement("div", {
+    "data-testid": testId,
     ref: ref,
-    gap: "space.100",
-    role: "group"
+    role: "group",
+    className: (0, _runtime.ax)([styles.root])
   }, children);
 });

package/dist/cjs/ui/popover-content/index.compiled.css

@@ -1,3 +1,4 @@
+._1pby1fw0{z-index:700}
 ._3um015vq{visibility:hidden}
 ._3um0ewfl{visibility:visible}
 ._lcxv1wug{pointer-events:auto}

package/dist/cjs/ui/popover-content/index.js

@@ -14,6 +14,9 @@ var _popper = require("@atlaskit/popper");
 var _context = require("../../controllers/context");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 var styles = {
+  root: "_1pby1fw0"
+};
+var visibilityStyles = {
   visible: "_lcxv1wug _3um0ewfl",
   hidden: "_lcxvglyw _3um015vq"
 };
@@ -69,7 +72,7 @@ var PopoverContent = exports.PopoverContent = function PopoverContent(_ref) {
     return /*#__PURE__*/React.createElement("div", {
       ref: ref,
       style: style,
-      className: (0, _runtime.ax)([styles[visibility]])
+      className: (0, _runtime.ax)([styles.root, visibilityStyles[visibility]])
     }, children);
   });
 };

package/dist/es2019/ui/controls/index.compiled.css

@@ -0,0 +1,3 @@
+
+._zulpu2gc{gap:var(--ds-space-100,8px)}._1e0c1txw{display:flex}
+._2lx21sbv{flex-direction:row-reverse}

package/dist/es2019/ui/controls/index.js

@@ -1,5 +1,11 @@
-import React, { forwardRef } from 'react';
-import { Flex } from '@atlaskit/primitives/compiled';
+/* index.tsx generated by @compiled/babel-plugin v0.36.1 */
+import "./index.compiled.css";
+import * as React from 'react';
+import { ax, ix } from "@compiled/react/runtime";
+import { forwardRef } from 'react';
+const styles = {
+  root: "_zulpu2gc _1e0c1txw _2lx21sbv"
+};
 /**
  * __Spotlight controls__
  *
@@ -9,10 +15,10 @@ export const SpotlightControls = /*#__PURE__*/forwardRef(({
   testId,
   children
 }, ref) => {
-  return /*#__PURE__*/React.createElement(Flex, {
-    testId: testId,
+  return /*#__PURE__*/React.createElement("div", {
+    "data-testid": testId,
     ref: ref,
-    gap: "space.100",
-    role: "group"
+    role: "group",
+    className: ax([styles.root])
   }, children);
 });

package/dist/es2019/ui/popover-content/index.compiled.css

@@ -1,3 +1,4 @@
+._1pby1fw0{z-index:700}
 ._3um015vq{visibility:hidden}
 ._3um0ewfl{visibility:visible}
 ._lcxv1wug{pointer-events:auto}

package/dist/es2019/ui/popover-content/index.js

@@ -6,6 +6,9 @@ import { useContext, useEffect } from 'react';
 import { Popper } from '@atlaskit/popper';
 import { SpotlightContext } from '../../controllers/context';
 const styles = {
+  root: "_1pby1fw0"
+};
+const visibilityStyles = {
   visible: "_lcxv1wug _3um0ewfl",
   hidden: "_lcxvglyw _3um015vq"
 };
@@ -62,6 +65,6 @@ export const PopoverContent = ({
   }) => /*#__PURE__*/React.createElement("div", {
     ref: ref,
     style: style,
-    className: ax([styles[visibility]])
+    className: ax([styles.root, visibilityStyles[visibility]])
   }, children));
 };

package/dist/esm/ui/controls/index.compiled.css

@@ -0,0 +1,3 @@
+
+._zulpu2gc{gap:var(--ds-space-100,8px)}._1e0c1txw{display:flex}
+._2lx21sbv{flex-direction:row-reverse}

package/dist/esm/ui/controls/index.js

@@ -1,5 +1,11 @@
-import React, { forwardRef } from 'react';
-import { Flex } from '@atlaskit/primitives/compiled';
+/* index.tsx generated by @compiled/babel-plugin v0.36.1 */
+import "./index.compiled.css";
+import * as React from 'react';
+import { ax, ix } from "@compiled/react/runtime";
+import { forwardRef } from 'react';
+var styles = {
+  root: "_zulpu2gc _1e0c1txw _2lx21sbv"
+};
 /**
  * __Spotlight controls__
  *
@@ -8,10 +14,10 @@ import { Flex } from '@atlaskit/primitives/compiled';
 export var SpotlightControls = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var testId = _ref.testId,
     children = _ref.children;
-  return /*#__PURE__*/React.createElement(Flex, {
-    testId: testId,
+  return /*#__PURE__*/React.createElement("div", {
+    "data-testid": testId,
     ref: ref,
-    gap: "space.100",
-    role: "group"
+    role: "group",
+    className: ax([styles.root])
   }, children);
 });

package/dist/esm/ui/popover-content/index.compiled.css

@@ -1,3 +1,4 @@
+._1pby1fw0{z-index:700}
 ._3um015vq{visibility:hidden}
 ._3um0ewfl{visibility:visible}
 ._lcxv1wug{pointer-events:auto}

package/dist/esm/ui/popover-content/index.js

@@ -6,6 +6,9 @@ import { useContext, useEffect } from 'react';
 import { Popper } from '@atlaskit/popper';
 import { SpotlightContext } from '../../controllers/context';
 var styles = {
+  root: "_1pby1fw0"
+};
+var visibilityStyles = {
   visible: "_lcxv1wug _3um0ewfl",
   hidden: "_lcxvglyw _3um015vq"
 };
@@ -61,7 +64,7 @@ export var PopoverContent = function PopoverContent(_ref) {
     return /*#__PURE__*/React.createElement("div", {
       ref: ref,
       style: style,
-      className: ax([styles[visibility]])
+      className: ax([styles.root, visibilityStyles[visibility]])
     }, children);
   });
 };

package/dist/types/ui/controls/index.d.ts

@@ -1,4 +1,8 @@
-import React, { type ReactNode } from 'react';
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import { type ReactNode } from 'react';
 export interface SpotlightControlsProps {
     /**
      * A `testId` prop is provided for specified elements, which is a unique
@@ -16,4 +20,4 @@ export interface SpotlightControlsProps {
  *
  * `SpotlightControls` groups spotlight control components.
  */
-export declare const SpotlightControls: React.ForwardRefExoticComponent<SpotlightControlsProps & React.RefAttributes<HTMLDivElement>>;
+export declare const SpotlightControls: import("react").ForwardRefExoticComponent<SpotlightControlsProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/types/ui/popover-target/index.d.ts

@@ -1,7 +1,7 @@
 /**
-* @jsxRuntime classic
-* @jsx jsx
-*/
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
 import { type ReactNode } from 'react';
 /**
  * __Target__

package/dist/types-ts4.5/ui/controls/index.d.ts

@@ -1,4 +1,8 @@
-import React, { type ReactNode } from 'react';
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import { type ReactNode } from 'react';
 export interface SpotlightControlsProps {
     /**
      * A `testId` prop is provided for specified elements, which is a unique
@@ -16,4 +20,4 @@ export interface SpotlightControlsProps {
  *
  * `SpotlightControls` groups spotlight control components.
  */
-export declare const SpotlightControls: React.ForwardRefExoticComponent<SpotlightControlsProps & React.RefAttributes<HTMLDivElement>>;
+export declare const SpotlightControls: import("react").ForwardRefExoticComponent<SpotlightControlsProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/types-ts4.5/ui/popover-target/index.d.ts

@@ -1,7 +1,7 @@
 /**
-* @jsxRuntime classic
-* @jsx jsx
-*/
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
 import { type ReactNode } from 'react';
 /**
  * __Target__

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/spotlight",
-	"version": "0.0.18",
+	"version": "0.1.0",
 	"description": "A spotlight introduces users to various points of interest across Atlassian through focused messages or multi-step tours.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -48,7 +48,6 @@
 		"@af/visual-regression": "workspace:^",
 		"@atlaskit/dropdown-menu": "^16.3.0",
 		"@atlaskit/ssr": "workspace:^",
-		"@atlaskit/visual-regression": "workspace:^",
 		"@testing-library/react": "^13.4.0",
 		"react-dom": "^18.2.0"
 	},