@atlaskit/ads-mcp 0.20.2 → 0.20.4

package/dist/cjs/tools/get-atlaskit-components/get-atlaskit-components-tool.js

@@ -0,0 +1,40 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getAtlaskitComponentsTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _atlaskitComponents = require("./atlaskit-components.codegen");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var getAtlaskitComponentsTool = exports.getAtlaskitComponentsTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
+    var components;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          components = _atlaskitComponents.atlaskitComponents.map(function (component) {
+            return {
+              name: component.name,
+              package: component.package
+            };
+          });
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(components, null, 2)
+            }]
+          });
+        case 2:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function getAtlaskitComponentsTool() {
+    return _ref.apply(this, arguments);
+  };
+}();

package/dist/cjs/tools/get-atlaskit-components/list-get-atlaskit-components-tool.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.listGetAtlaskitComponentsTool = void 0;
+var _zod = require("zod");
+var _helpers = require("../../helpers");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var listGetAtlaskitComponentsTool = exports.listGetAtlaskitComponentsTool = {
+  name: 'atlaskit_get_components',
+  description: "Returns the names and packages of all atlaskit components excluding components covered by the Atlassian Design System.\n\nWHEN TO USE:\nUse this when you want to see what components are available without the full metadata payload.\n\nNo parameters.",
+  annotations: {
+    title: 'Get all Atlaskit components',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _helpers.zodToJsonSchema)(_zod.z.object({}))
+};

package/dist/cjs/tools/get-guidelines/get-guidelines-input-schema.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getGuidelinesInputSchema = void 0;
+var _zod = require("zod");
+var getGuidelinesInputSchema = exports.getGuidelinesInputSchema = _zod.z.object({
+  terms: _zod.z.array(_zod.z.string()).default([]).describe('Search terms matched against guideline keywords and body (fuzzy). Examples: `["empty state", "voice tone"]`, `["color tokens", "spacing"]`, `["elevation", "grid"]`. Omit or use an empty array to return **all** guidelines as Markdown.').optional(),
+  limit: _zod.z.number().default(1).describe('Max matches **per term** when `terms` is non-empty (default 1). Ignored when returning all guidelines.').optional()
+});

package/dist/cjs/tools/get-guidelines/{index.js → get-guidelines-tool.js}

@@ -4,31 +4,14 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.listGetGuidelinesTool = exports.getGuidelinesTool = exports.getGuidelinesInputSchema = void 0;
+exports.getGuidelinesTool = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _fuse = _interopRequireDefault(require("fuse.js"));
-var _zod = require("zod");
-var _helpers = require("../../helpers");
+var _cleanQuery = require("../../helpers/clean-query");
 var _guidelinesStructuredContent = require("./guidelines-structured-content.codegen");
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
-var getGuidelinesInputSchema = exports.getGuidelinesInputSchema = _zod.z.object({
-  terms: _zod.z.array(_zod.z.string()).default([]).describe('Search terms matched against guideline keywords and body (fuzzy). Examples: `["empty state", "voice tone"]`, `["color tokens", "spacing"]`, `["elevation", "grid"]`. Omit or use an empty array to return **all** guidelines as Markdown.').optional(),
-  limit: _zod.z.number().default(1).describe('Max matches **per term** when `terms` is non-empty (default 1). Ignored when returning all guidelines.').optional()
-});
-var listGetGuidelinesTool = exports.listGetGuidelinesTool = {
-  name: 'ads_get_guidelines',
-  description: "Returns Atlassian Design System (ADS) **foundations** guidelines as Markdown: the bundled design-system-docs foundations set (not component API docs).\n\nTOPIC COVERAGE:\n- **Content & UX writing**: messaging types (empty state, error, success, warning, info, feature discovery), voice and tone, inclusive language, grammar and style, date/time copy handoff, vocabulary pointers.\n- **Visual foundations**: color (roles, accents, palette, charts, pickers), borders and radius, elevation and z-index, spacing and layout primitives (box/inline/stack), grid, iconography, logos.\n- **Design tokens**: concepts, themes, migration, using tokens in code and in Figma.\n- **Typography**: typefaces, scale, applying text styles and tokens.\n- **Accessibility overview**: building accessible apps and related foundations pages bundled here.\n\nWhen working with content, use this tool alongside the Context Engine MCP tool `get_content_standards_docs` for Atlassian-wide content standards (CDSTD/BAIT-style org guidance); this tool supplies ADS-specific foundations.\n\nWHAT YOU GET:\n- With `terms`: fuzzy search over keywords and content; concatenated Markdown for matches.\n- Without `terms` (or empty): the full guideline set as Markdown.\n\nWHEN TO USE:\nUse this when you are **building or updating a visual interface**, **writing or reviewing user-facing copy**, or need to **answer foundations questions** about ADS: content patterns, visual appearance, design tokens, typography, spacing, color, grid, motion, and related topics shipped in this bundle.\n\nIt is **not** for picking a component\u2019s props or package (use `ads_plan` / `ads_search_components`) or for interactive accessibility rules and patterns (use `ads_get_a11y_guidelines`, with Context Engine `get_accessibility_docs` for org-wide a11y standards).",
-  annotations: {
-    title: 'Get ADS guidelines (content, a11y, visual design, design tokens, typography)',
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true
-  },
-  inputSchema: (0, _helpers.zodToJsonSchema)(getGuidelinesInputSchema)
-};
 var getGuidelinesTool = exports.getGuidelinesTool = /*#__PURE__*/function () {
   var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
     var _params$terms, terms, _params$limit, limit, searchTerms, guidelineDocs, allGuidelinesMarkdown, fuse, results, seen, uniqueResults, matchedGuidelines, formattedGuidelines;
@@ -36,7 +19,7 @@ var getGuidelinesTool = exports.getGuidelinesTool = /*#__PURE__*/function () {
       while (1) switch (_context.prev = _context.next) {
         case 0:
           _params$terms = params.terms, terms = _params$terms === void 0 ? [] : _params$terms, _params$limit = params.limit, limit = _params$limit === void 0 ? 1 : _params$limit;
-          searchTerms = terms.filter(Boolean).map(_helpers.cleanQuery);
+          searchTerms = terms.filter(Boolean).map(_cleanQuery.cleanQuery);
           guidelineDocs = _guidelinesStructuredContent.guidelinesStructuredContent; // If no search terms provided, return all guidelines formatted as Markdown
           if (!(searchTerms.length === 0)) {
             _context.next = 6;

package/dist/cjs/tools/get-guidelines/list-get-guidelines-tool.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.listGetGuidelinesTool = void 0;
+var _zodToJsonSchema = require("../../helpers/zod-to-json-schema");
+var _getGuidelinesInputSchema = require("./get-guidelines-input-schema");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var listGetGuidelinesTool = exports.listGetGuidelinesTool = {
+  name: 'ads_get_guidelines',
+  description: "Returns Atlassian Design System (ADS) **foundations** guidelines as Markdown: the bundled design-system-docs foundations set (not component API docs).\n\nTOPIC COVERAGE:\n- **Content & UX writing**: messaging types (empty state, error, success, warning, info, feature discovery), voice and tone, inclusive language, grammar and style, date/time copy handoff, vocabulary pointers.\n- **Visual foundations**: color (roles, accents, palette, charts, pickers), borders and radius, elevation and z-index, spacing and layout primitives (box/inline/stack), grid, iconography, logos.\n- **Design tokens**: concepts, themes, migration, using tokens in code and in Figma.\n- **Typography**: typefaces, scale, applying text styles and tokens.\n- **Accessibility overview**: building accessible apps and related foundations pages bundled here.\n\nWhen working with content, use this tool alongside the Context Engine MCP tool `get_content_standards_docs` for Atlassian-wide content standards (CDSTD/BAIT-style org guidance); this tool supplies ADS-specific foundations.\n\nWHAT YOU GET:\n- With `terms`: fuzzy search over keywords and content; concatenated Markdown for matches.\n- Without `terms` (or empty): the full guideline set as Markdown.\n\nWHEN TO USE:\nUse this when you are **building or updating a visual interface**, **writing or reviewing user-facing copy**, or need to **answer foundations questions** about ADS: content patterns, visual appearance, design tokens, typography, spacing, color, grid, motion, and related topics shipped in this bundle.\n\nIt is **not** for picking a component\u2019s props or package (use `ads_plan` / `ads_search_components`) or for interactive accessibility rules and patterns (use `ads_get_a11y_guidelines`, with Context Engine `get_accessibility_docs` for org-wide a11y standards).",
+  annotations: {
+    title: 'Get ADS guidelines (content, a11y, visual design, design tokens, typography)',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(_getGuidelinesInputSchema.getGuidelinesInputSchema)
+};

package/dist/cjs/tools/get-lint-rules/get-lint-rules-input-schema.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getLintRulesInputSchema = void 0;
+var _zod = require("zod");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var getLintRulesInputSchema = exports.getLintRulesInputSchema = _zod.z.object({
+  terms: _zod.z.array(_zod.z.string()).default([]).describe('Search terms matched against rule name, description, and docs body (fuzzy unless \`exactName\` is true). Example: `["icon-label", "xcss", "design token"]`. Omit or empty: return **all** rules as JSON.').optional(),
+  limit: _zod.z.number().default(1).describe('Max matches **per term** when searching (default 1). Not used when returning all rules.').optional(),
+  exactName: _zod.z.boolean().default(false).describe('If true, resolve each term by **exact** ESLint rule name (case-insensitive). If false, fuzzy search across name, description, and content.').optional()
+});

package/dist/cjs/tools/get-lint-rules/{index.js → get-lint-rules-tool.js}

@@ -4,32 +4,14 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.listGetLintRulesTool = exports.getLintRulesTool = exports.getLintRulesInputSchema = void 0;
+exports.getLintRulesTool = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _fuse = _interopRequireDefault(require("fuse.js"));
-var _zod = require("zod");
-var _helpers = require("../../helpers");
+var _cleanQuery = require("../../helpers/clean-query");
 var _lintRulesStructuredContent = require("./lint-rules-structured-content.codegen");
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
-var getLintRulesInputSchema = exports.getLintRulesInputSchema = _zod.z.object({
-  terms: _zod.z.array(_zod.z.string()).default([]).describe('Search terms matched against rule name, description, and docs body (fuzzy unless \`exactName\` is true). Example: `["icon-label", "xcss", "design token"]`. Omit or empty: return **all** rules as JSON.').optional(),
-  limit: _zod.z.number().default(1).describe('Max matches **per term** when searching (default 1). Not used when returning all rules.').optional(),
-  exactName: _zod.z.boolean().default(false).describe('If true, resolve each term by **exact** ESLint rule name (case-insensitive). If false, fuzzy search across name, description, and content.').optional()
-});
-var listGetLintRulesTool = exports.listGetLintRulesTool = {
-  name: 'ads_get_lint_rules',
-  description: "Returns documentation for **Constellation** (Atlassian Design System) ESLint rules shipped with this MCP\u2014rule purpose, examples, and fixes where available.\n\nWHAT YOU GET:\n- No `terms`: JSON array of all rule payloads.\n- With `terms`: fuzzy search (or exact rule name when `exactName` is true); JSON for one or more matching rules.\n\nWHEN TO USE:\nExplaining or fixing an ESLint message from ADS rules (e.g. `icon-label`, `ensure-proper-xcss-usage`, `no-deprecated-apis`), or browsing rule docs without opening the repo. Prefer this over guessing from rule id alone.\n\nThis tool does not run ESLint; it only returns bundled documentation.",
-  annotations: {
-    title: 'Get ADS ESLint rule docs',
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true
-  },
-  inputSchema: (0, _helpers.zodToJsonSchema)(getLintRulesInputSchema)
-};
 var getLintRulesTool = exports.getLintRulesTool = /*#__PURE__*/function () {
   var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
     var _params$terms, terms, _params$limit, limit, _params$exactName, exactName, searchTerms, ruleDocs, _payload, exactNameMatches, _payload2, fuse, results, uniqueResults, matchedRules, payload;
@@ -37,7 +19,7 @@ var getLintRulesTool = exports.getLintRulesTool = /*#__PURE__*/function () {
       while (1) switch (_context.prev = _context.next) {
         case 0:
           _params$terms = params.terms, terms = _params$terms === void 0 ? [] : _params$terms, _params$limit = params.limit, limit = _params$limit === void 0 ? 1 : _params$limit, _params$exactName = params.exactName, exactName = _params$exactName === void 0 ? false : _params$exactName;
-          searchTerms = terms.filter(Boolean).map(_helpers.cleanQuery);
+          searchTerms = terms.filter(Boolean).map(_cleanQuery.cleanQuery);
           ruleDocs = _lintRulesStructuredContent.lintRulesMcpStructuredContent; // If no search terms provided, return all rules as JSON array
           if (!(searchTerms.length === 0)) {
             _context.next = 6;

package/dist/cjs/tools/get-lint-rules/list-get-lint-rules-tool.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.listGetLintRulesTool = void 0;
+var _zodToJsonSchema = require("../../helpers/zod-to-json-schema");
+var _getLintRulesInputSchema = require("./get-lint-rules-input-schema");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var listGetLintRulesTool = exports.listGetLintRulesTool = {
+  name: 'ads_get_lint_rules',
+  description: "Returns documentation for **Constellation** (Atlassian Design System) ESLint rules shipped with this MCP\u2014rule purpose, examples, and fixes where available.\n\nWHAT YOU GET:\n- No `terms`: JSON array of all rule payloads.\n- With `terms`: fuzzy search (or exact rule name when `exactName` is true); JSON for one or more matching rules.\n\nWHEN TO USE:\nExplaining or fixing an ESLint message from ADS rules (e.g. `icon-label`, `ensure-proper-xcss-usage`, `no-deprecated-apis`), or browsing rule docs without opening the repo. Prefer this over guessing from rule id alone.\n\nThis tool does not run ESLint; it only returns bundled documentation.",
+  annotations: {
+    title: 'Get ADS ESLint rule docs',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(_getLintRulesInputSchema.getLintRulesInputSchema)
+};

package/dist/cjs/tools/i18n-conversion/i18n-conversion-input-schema.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.i18nConversionInputSchema = void 0;
+var _zod = require("zod");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var i18nConversionInputSchema = exports.i18nConversionInputSchema = _zod.z.object({
+  guide: _zod.z.enum(['hardcoded-string-to-formatmessage']).describe('Which bundled guide to return. Currently only `hardcoded-string-to-formatmessage` (JSX literals → `formatMessage` / intl patterns).')
+});

package/dist/cjs/tools/i18n-conversion/i18n-conversion-tool.js

@@ -0,0 +1,33 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.i18nConversionTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _guide = require("./guide");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var i18nConversionTool = exports.i18nConversionTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(_params) {
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(_guide.i18nConversionGuide, null, 2)
+            }]
+          });
+        case 1:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function i18nConversionTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();

package/dist/cjs/tools/i18n-conversion/{index.js → list-i18n-conversion-tool.js}

@@ -1,20 +1,13 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.listI18nConversionTool = exports.i18nConversionTool = exports.i18nConversionInputSchema = void 0;
-var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
-var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
-var _zod = require("zod");
-var _helpers = require("../../helpers");
-var _guide = require("./guide");
+exports.listI18nConversionTool = void 0;
+var _zodToJsonSchema = require("../../helpers/zod-to-json-schema");
+var _i18nConversionInputSchema = require("./i18n-conversion-input-schema");
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
-var i18nConversionInputSchema = exports.i18nConversionInputSchema = _zod.z.object({
-  guide: _zod.z.enum(['hardcoded-string-to-formatmessage']).describe('Which bundled guide to return. Currently only `hardcoded-string-to-formatmessage` (JSX literals → `formatMessage` / intl patterns).')
-});
 var listI18nConversionTool = exports.listI18nConversionTool = {
   name: 'ads_i18n_conversion_guide',
   description: "Returns a **bundled** step-by-step guide for replacing hardcoded UI strings with `formatMessage` (and related patterns) using @atlassian/jira-intl or react-intl-next: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.\n\nWhen working with i18n or hardcoded UI strings, use this tool alongside the Context Engine MCP tool `get_i18n_docs` for Atlassian-wide Traduki / i18n standards (message definition, extraction, pluralisation, formatting, workflow); this tool supplies the concrete hardcoded-string \u2192 `formatMessage` playbook bundled in ADS MCP.\n\nWHEN TO USE / TYPICAL TRIGGERS:\n- Refactoring JSX or TS literals to i18n; \"fix hardcoded string(s)\", \"convert hardcoded string in [file]\", \"literal string in JSX\".\n- \"Convert to i18n\", \"convert to formatMessage\", \"translate this string\", \"internationalize this string\", \"i18n this string\".\n- \"Use formatMessage\", \"use FormattedMessage\", \"wrap in formatMessage\", \"fix literal string\".\n- ESLint: `Literal string in JSX content should be internationalized. Use FormattedMessage or intl.formatMessage()`.\n- ESLint: `@atlassian/i18n/no-literal-string-in-jsx`.",
@@ -25,26 +18,5 @@ var listI18nConversionTool = exports.listI18nConversionTool = {
     idempotentHint: true,
     openWorldHint: false
   },
-  inputSchema: (0, _helpers.zodToJsonSchema)(i18nConversionInputSchema)
-};
-var i18nConversionTool = exports.i18nConversionTool = /*#__PURE__*/function () {
-  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(_params) {
-    return _regenerator.default.wrap(function _callee$(_context) {
-      while (1) switch (_context.prev = _context.next) {
-        case 0:
-          return _context.abrupt("return", {
-            content: [{
-              type: 'text',
-              text: JSON.stringify(_guide.i18nConversionGuide, null, 2)
-            }]
-          });
-        case 1:
-        case "end":
-          return _context.stop();
-      }
-    }, _callee);
-  }));
-  return function i18nConversionTool(_x) {
-    return _ref.apply(this, arguments);
-  };
-}();
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(_i18nConversionInputSchema.i18nConversionInputSchema)
+};

package/dist/cjs/tools/migration-guides/get-available-migration-ids.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getAvailableMigrationIds = void 0;
+var _migrationRegistry = require("./migration-registry");
+/**
+ * Migration registry - central place to register all available migrations
+ *
+ * To add a new migration:
+ * 1. Create a new file in ./migrations/ with your MigrationGuide(s)
+ * 2. Import and add to the registry below
+ * 3. The tool will automatically include it in the available options
+ */
+
+/**
+ * Get all available migration IDs for use in the tool schema
+ */
+var getAvailableMigrationIds = exports.getAvailableMigrationIds = function getAvailableMigrationIds() {
+  return Object.keys(_migrationRegistry.migrationRegistry);
+};

package/dist/cjs/tools/migration-guides/get-available-migrations-description.js

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getAvailableMigrationsDescription = void 0;
+var _migrationRegistry = require("./migration-registry");
+/**
+ * Migration registry - central place to register all available migrations
+ *
+ * To add a new migration:
+ * 1. Create a new file in ./migrations/ with your MigrationGuide(s)
+ * 2. Import and add to the registry below
+ * 3. The tool will automatically include it in the available options
+ */
+
+/**
+ * Get a formatted list of available migrations with descriptions
+ * Useful for tool descriptions and help text
+ */
+var getAvailableMigrationsDescription = exports.getAvailableMigrationsDescription = function getAvailableMigrationsDescription() {
+  return Object.values(_migrationRegistry.migrationRegistry).map(function (m) {
+    return "- \"".concat(m.id, "\": ").concat(m.description);
+  });
+};

package/dist/cjs/tools/migration-guides/list-migration-guides-tool.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.listMigrationGuidesTool = void 0;
+var _zodToJsonSchema = require("../../helpers/zod-to-json-schema");
+var _getAvailableMigrationsDescription = require("./get-available-migrations-description");
+var _migrationGuidesInputSchema = require("./migration-guides-input-schema");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var listMigrationGuidesTool = exports.listMigrationGuidesTool = {
+  name: 'ads_migration_guides',
+  description: "Returns a structured Atlassian Design System (ADS) **migration guide** for a known package or API migration (before/after examples, best practices, links).\n\nWHEN TO USE:\nYou are upgrading or refactoring code between ADS packages or APIs and need the official migration pattern for a specific id listed below.\n\nPass **both** `migration` and `description` using a **matching pair** from the enum (schema enforces valid combinations).\n\nAvailable migrations:\n".concat((0, _getAvailableMigrationsDescription.getAvailableMigrationsDescription)()),
+  annotations: {
+    title: 'ADS Migration Guides',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  inputSchema: (0, _zodToJsonSchema.zodToJsonSchema)(_migrationGuidesInputSchema.migrationGuidesInputSchema)
+};

package/dist/cjs/tools/migration-guides/migration-guides-input-schema.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.migrationGuidesInputSchema = void 0;
+var _zod = require("zod");
+var _getAvailableMigrationIds = require("./get-available-migration-ids");
+var _getAvailableMigrationsDescription = require("./get-available-migrations-description");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var migrationIds = (0, _getAvailableMigrationIds.getAvailableMigrationIds)();
+var migrationDescriptions = (0, _getAvailableMigrationsDescription.getAvailableMigrationsDescription)();
+var migrationGuidesInputSchema = exports.migrationGuidesInputSchema = _zod.z.object({
+  migration: _zod.z.enum(migrationIds).describe('Migration id from the registry. Must match the guide you want (see tool description list).'),
+  description: _zod.z.enum(migrationDescriptions).describe('Human-readable migration label that pairs with `migration` in the schema—choose the entry that matches the selected id.')
+});

package/dist/cjs/tools/migration-guides/{index.js → migration-guides-tool.js}

@@ -4,34 +4,13 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.migrationGuidesTool = exports.migrationGuidesInputSchema = exports.listMigrationGuidesTool = void 0;
+exports.migrationGuidesTool = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
-var _zod = require("zod");
-var _helpers = require("../../helpers");
+var _getAvailableMigrationIds = require("./get-available-migration-ids");
 var _migrationRegistry = require("./migration-registry");
-var _registry = require("./registry");
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
-// Build the enum dynamically from the registry
-var migrationIds = (0, _registry.getAvailableMigrationIds)();
-var migrationDescriptions = (0, _registry.getAvailableMigrationsDescription)();
-var migrationGuidesInputSchema = exports.migrationGuidesInputSchema = _zod.z.object({
-  migration: _zod.z.enum(migrationIds).describe('Migration id from the registry. Must match the guide you want (see tool description list).'),
-  description: _zod.z.enum(migrationDescriptions).describe('Human-readable migration label that pairs with `migration` in the schema—choose the entry that matches the selected id.')
-});
-var listMigrationGuidesTool = exports.listMigrationGuidesTool = {
-  name: 'ads_migration_guides',
-  description: "Returns a structured Atlassian Design System (ADS) **migration guide** for a known package or API migration (before/after examples, best practices, links).\n\nWHEN TO USE:\nYou are upgrading or refactoring code between ADS packages or APIs and need the official migration pattern for a specific id listed below.\n\nPass **both** `migration` and `description` using a **matching pair** from the enum (schema enforces valid combinations).\n\nAvailable migrations:\n".concat((0, _registry.getAvailableMigrationsDescription)()),
-  annotations: {
-    title: 'ADS Migration Guides',
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: false
-  },
-  inputSchema: (0, _helpers.zodToJsonSchema)(migrationGuidesInputSchema)
-};
 var migrationGuidesTool = exports.migrationGuidesTool = /*#__PURE__*/function () {
   var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
     var migration, guide;
@@ -49,7 +28,7 @@ var migrationGuidesTool = exports.migrationGuidesTool = /*#__PURE__*/function ()
               type: 'text',
               text: JSON.stringify({
                 error: "Unknown migration: ".concat(migration),
-                availableMigrations: (0, _registry.getAvailableMigrationIds)(),
+                availableMigrations: (0, _getAvailableMigrationIds.getAvailableMigrationIds)(),
                 suggestion: 'Please use one of the available migration IDs listed above.'
               }, null, 2)
             }]

package/dist/cjs/tools/migration-guides/migration-registry.js

@@ -6,5 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.migrationRegistry = void 0;
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
-var _onboardingToSpotlight = require("./migrations/onboarding-to-spotlight");
-var migrationRegistry = exports.migrationRegistry = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _onboardingToSpotlight.onboardingJiraSpotlight.id, _onboardingToSpotlight.onboardingJiraSpotlight), _onboardingToSpotlight.onboardingSingleStep.id, _onboardingToSpotlight.onboardingSingleStep), _onboardingToSpotlight.onboardingMultiStep.id, _onboardingToSpotlight.onboardingMultiStep), _onboardingToSpotlight.onboardingWithMotion.id, _onboardingToSpotlight.onboardingWithMotion);
+var _onboardingJiraSpotlight = require("./migrations/onboarding-jira-spotlight");
+var _onboardingMultiStep = require("./migrations/onboarding-multi-step");
+var _onboardingSingleStep = require("./migrations/onboarding-single-step");
+var _onboardingWithMotion = require("./migrations/onboarding-with-motion");
+var migrationRegistry = exports.migrationRegistry = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _onboardingJiraSpotlight.onboardingJiraSpotlight.id, _onboardingJiraSpotlight.onboardingJiraSpotlight), _onboardingSingleStep.onboardingSingleStep.id, _onboardingSingleStep.onboardingSingleStep), _onboardingMultiStep.onboardingMultiStep.id, _onboardingMultiStep.onboardingMultiStep), _onboardingWithMotion.onboardingWithMotion.id, _onboardingWithMotion.onboardingWithMotion);

package/dist/cjs/tools/migration-guides/migrations/onboarding-jira-spotlight.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.onboardingJiraSpotlight = void 0;
+var additionalResources = 'Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context';
+var onboardingJiraSpotlight = exports.onboardingJiraSpotlight = {
+  id: 'jira-spotlight',
+  title: 'JiraSpotlight Migration',
+  description: 'Use when code contains `JiraSpotlight` import from `@atlassian/jira-spotlight`',
+  fromPackage: '@atlassian/jira-spotlight',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Internal <JiraSpotlight /> migration',
+    description: 'Internal migrations are possible for JiraSpotlight usages which only pass simple/textual content to JiraSpotlight children',
+    before: "\n// file1.tsx\nimport { JiraSpotlight } from '@atlassian/jira-spotlight/src/ui/jira-spotlight.tsx';\n\nexport const OnboardingSpotlightWrapper = () => {\n\tconst spotlightId = 'some-unique-identifier'\n\tconst { dark, light } = spotlightImageUrls[spotlightId];\n\tconst imageUrl = colorMode === 'dark' ? dark : light;\n\n\treturn (\n\t\t<JiraSpotlight\n\t\t\timage={imageUrl}\n\t\t\tactions={[\n\t\t\t\t{\n\t\t\t\t\tonClick,\n\t\t\t\t\ttext: formatMessage(dismiss),\n\t\t\t\t},\n\t\t\t]}\n\t\t\theading={formatMessage(heading)}\n\t\t\ttarget={spotlightId}\n\t\t\tkey={spotlightId}\n\t\t\ttargetRadius={3}\n\t\t\ttargetBgColor={token('elevation.surface')}\n\t\t\tmessageId={spotlightId}\n\t\t\tmessageType=\"transactional\"\n\t\t\tdialogWidth={275}\n\t\t>\n\t\t\t{formatMessage(body)}\n\t\t</JiraSpotlight>\n\t);\n}\n\n// file2.tsx\nimport { SpotlightTarget } from '@atlaskit/onboarding';\n\nconst spotlightId = 'some-unique-identifier'\n\nexport const SomeFeature = () => {\n\treturn (\n\t\t<SpotlightTarget name={spotlightId}>\n\t\t\t// Target code\n\t\t</SpotlightTarget>\n\t);\n}\n",
+    after: "\n// file1.tsx\nimport { JiraSpotlight } from '@atlassian/jira-spotlight/src/ui/jira-spotlight.tsx';\n\nexport const OnboardingSpotlightWrapper = () => {\n\tconst spotlightId = 'some-unique-identifier'\n\tconst { dark, light } = spotlightImageUrls[spotlightId];\n\tconst imageUrl = colorMode === 'dark' ? dark : light;\n\n\treturn (\n\t\t<JiraSpotlight\n\t\t\tisMigrated // isMigrated prop passed\n\t\t\timage={imageUrl}\n\t\t\tactions={[\n\t\t\t\t{\n\t\t\t\t\tonClick,\n\t\t\t\t\ttext: formatMessage(dismiss),\n\t\t\t\t},\n\t\t\t]}\n\t\t\theading={formatMessage(heading)}\n\t\t\ttarget={spotlightId}\n\t\t\tkey={spotlightId}\n\t\t\ttargetRadius={3}\n\t\t\ttargetBgColor={token('elevation.surface')}\n\t\t\tmessageId={spotlightId}\n\t\t\tmessageType=\"transactional\"\n\t\t\tdialogWidth={275}\n\t\t>\n\t\t\t{formatMessage(body)}\n\t\t</JiraSpotlight>\n\t);\n}\n\n// file2.tsx\n// Updated SpotlightTarget import statement\nimport { SpotlightTarget } from '@atlassian/jira-spotlight/src/ui/SpotlightTarget.tsx';\n\nexport const SomeFeature = () => {\n\tconst spotlightId = 'some-unique-identifier'\n\n\treturn (\n\t\t<SpotlightTarget name={spotlightId}>\n\t\t\t// Target code\n\t\t</SpotlightTarget>\n\t);\n}\n\t\t\t",
+    explanation: "Key changes when migrating a JiraSpotlight:\n- A JiraSpotlight and a SpotlightTarget are part of the same usage if they share a spotlightId value - Referenced in JiraSpotlight.target and SpotlightTarget.name props\n- Pass isMigrated={true} to JiraSpotlight.\n- Update SpotlightTarget import statment from '@atlaskit/onboarding' to '@atlassian/jira-spotlight/src/ui/SpotlightTarget.tsx';\n- These changes allow switching the internal implementation to '@atlaskit/spotlight' via a feature flag.\n- This internal migration is only possible for usages that don't rely too heavily on the 'children' prop, as complex values, like heading, images, etc passed to 'children' are difficult to parse.\n"
+  }, {
+    title: 'Complex <JiraSpotlight /> migration',
+    description: 'Complex migrations are necessary for JiraSpotlight usages that make heavy use of the `children` prop to achieve customisation instead of relying on the `heading`, `body`, `image`, and/or `actions` props.',
+    before: "\n// file1.tsx\nimport { JiraSpotlight } from '@atlassian/jira-spotlight/src/ui/jira-spotlight.tsx';\n\nexport const OnboardingSpotlightWrapper = () => {\n\tconst spotlightId = 'some-unique-identifier'\n\tconst { dark, light } = spotlightImageUrls[spotlightId];\n\tconst imageUrl = colorMode === 'dark' ? dark : light;\n\n\treturn (\n\t\t<JiraSpotlight\n\t\t\ttarget={spotlightId}\n\t\t\ttargetRadius={3}\n\t\t\tdialogPlacement=''\n\t\t\ttargetBgColor={token('elevation.surface')}\n\t\t\tmessageId={spotlightId}\n\t\t\tmessageType=\"transactional\"\n\t\t\tdialogWidth={275}\n\t\t>\n\t\t\t<CustomSpotlightInner>\n\t\t\t\t{imageUrl}\n\t\t\t\t{formatMessage(heading)}\n\t\t\t\t{formatMessage(body)}\n\t\t\t\t<CustomSpotlightAction>\n\t\t\t\t\t{formatMessage(dismiss)}\n\t\t\t\t</CustomSpotlightAction>\n\t\t\t</CustomSpotlightInner>\n\t\t</JiraSpotlight>\n\t);\n}\n\n// file2.tsx\nimport { SpotlightTarget } from '@atlaskit/onboarding';\n\nconst spotlightId = 'some-unique-identifier'\n\nexport const SomeFeature = () => {\n\treturn (\n\t\t<SpotlightTarget name={spotlightId}>\n\t\t\t// Target code\n\t\t</SpotlightTarget>\n\t);\n}\n",
+    after: "\n// file2.tsx - Spotlight code has been co-located to the targeted element\nimport { Text } from '@atlaskit/primitives/compiled';\nimport {\n  PopoverContent,\n  PopoverProvider,\n  PopoverTarget,\n  SpotlightActions,\n  SpotlightBody,\n  SpotlightCard,\n  SpotlightControls,\n  SpotlightDismissControl,\n  SpotlightFooter,\n  SpotlightHeader,\n  SpotlightHeadline,\n  SpotlightPrimaryAction,\n} from '@atlaskit/spotlight';\nimport Image from '@atlaskit/image';\nimport { ChoreographedComponent } from '@atlassian/jira-spotlight/src/ui/ChoreographedComponent.tsx';\n\nexport const SomeFeature = () => {\n\tconst { dark, light } = spotlightImageUrls[spotlightId];\n\n\tconst [isSpotlightVisible, actions] = useListViewOnboarding({\n\t\tprojectId: String(projectData.id),\n\t\tid: spotlightId,\n\t});\n\n\treturn (\n\t\t<PopoverProvider>\n\t\t\t<PopoverTarget>{renderTrigger(isSpotlightVisible)}</PopoverTarget>\n\t\t\t<ChoreographedComponent messageId={spotlightId} messageType=\"transactional\">\n\t\t\t\t<PopoverContent isVisible={isSpotlightVisible} placement=\"bottom-start\" dismiss={onClick}>\n\t\t\t\t\t<SpotlightCard>\n\t\t\t\t\t\t<SpotlightHeader>\n\t\t\t\t\t\t\t<SpotlightHeadline>{formatMessage(heading)}</SpotlightHeadline>\n\t\t\t\t\t\t\t<SpotlightControls>\n\t\t\t\t\t\t\t\t<SpotlightDismissControl />\n\t\t\t\t\t\t\t</SpotlightControls>\n\t\t\t\t\t\t</SpotlightHeader>\n\t\t\t\t\t\t<SpotlightMedia>\n\t\t\t\t\t\t\t<Image src={light} srcDark={dark} alt=\"\" />\n\t\t\t\t\t\t</SpotlightMedia>\n\t\t\t\t\t\t<SpotlightBody>\n\t\t\t\t\t\t\t<Text>{formatMessage(body)}</Text>\n\t\t\t\t\t\t</SpotlightBody>\n\t\t\t\t\t\t<SpotlightFooter>\n\t\t\t\t\t\t\t<SpotlightActions>\n\t\t\t\t\t\t\t\t<SpotlightPrimaryAction onClick={onClick}>\n\t\t\t\t\t\t\t\t\t{formatMessage(dismiss)}\n\t\t\t\t\t\t\t\t</SpotlightPrimaryAction>\n\t\t\t\t\t\t\t</SpotlightActions>\n\t\t\t\t\t\t</SpotlightFooter>\n\t\t\t\t\t</SpotlightCard>\n\t\t\t\t</PopoverContent>\n\t\t\t</ChoreographedComponent>\n\t\t</PopoverProvider>\n\t);\n};",
+    explanation: "Key changes when migrating a single step spotlight:\n- Replace JiraSpotlight with ChoreographedComponent from '@atlassian/jira-spotlight'.\n- PopoverProvider maintains internal Spotlight state.\n- Replace SpotlightTarget with PopoverTarget - wraps the element to highlight\n- Replace Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning\n- 'heading' becomes SpotlightHeadline inside SpotlightHeader\n- 'actions' becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)\n- 'body' content moves into SpotlightBody wrapped with Text component\n- Add SpotlightDismissControl inside SpotlightControls for the close button\n- The 'target' and/or 'targetName' prop is replaced with PopoverTarget directly wrapping the target element\n- 'dialogPlacement' prop becomes 'placement' on PopoverContent. Mapping: \"top right\" \u2192 \"top-start\", \"top center\" \u2192 \"top\", \"top left\" \u2192 \"top-end\", \"right bottom\" \u2192 \"right-start\", \"right middle\" \u2192 \"right-start | right-end\", \"right top\" \u2192 \"right-end\", \"bottom left\" \u2192 \"bottom-end\", \"bottom center\" \u2192 \"bottom\", \"bottom right\" \u2192 \"bottom-start\", \"left top\" \u2192 \"left-end\", \"left middle\" \u2192 \"left-start | left-end\", \"left bottom\" \u2192 \"left-start\"'"
+  }],
+  bestPractices: [],
+  additionalResources: additionalResources
+};

package/dist/cjs/tools/migration-guides/migrations/onboarding-multi-step.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.onboardingMultiStep = void 0;
+var additionalResources = 'Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context';
+var onboardingMultiStep = exports.onboardingMultiStep = {
+  id: 'multi-step',
+  title: 'Multi Step Spotlight Tour Migration',
+  description: 'Migrate a multi-step spotlight tour from @atlaskit/onboarding to @atlaskit/spotlight',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate multi step spotlight tour',
+    description: 'Replace the single SpotlightManager pattern with multiple PopoverProvider instances, one for each target in the tour',
+    before: "import React, { useState } from 'react';\nimport Button, { IconButton } from '@atlaskit/button/new';\nimport CommentAddIcon from '@atlaskit/icon/core/comment-add';\nimport CopyIcon from '@atlaskit/icon/core/copy';\nimport {\n  Spotlight,\n  SpotlightManager,\n  SpotlightTarget,\n  SpotlightTransition,\n} from '@atlaskit/onboarding';\n\nconst OnboardingTour = () => {\n  const [activeSpotlight, setActiveSpotlight] = useState<null | number>(null);\n  const start = () => setActiveSpotlight(0);\n  const next = () => setActiveSpotlight((activeSpotlight || 0) + 1);\n  const back = () => setActiveSpotlight((activeSpotlight || 1) - 1);\n  const end = () => setActiveSpotlight(null);\n\n  const renderActiveSpotlight = () => {\n    const spotlights = [\n      <Spotlight\n        actions={[\n          { onClick: () => next(), text: 'Next' },\n          { onClick: () => end(), text: 'Dismiss', appearance: 'subtle' },\n        ]}\n        heading=\"Add a comment\"\n        target=\"comment\"\n        key=\"comment\"\n      >\n        Quickly add a comment to the work item.\n      </Spotlight>,\n      <Spotlight\n        actions={[\n          { onClick: () => end(), text: 'Done' },\n          { onClick: () => back(), text: 'Back', appearance: 'subtle' },\n        ]}\n        heading=\"Copy code\"\n        target=\"copy\"\n        key=\"copy\"\n      >\n        Click to copy the example code to your clipboard.\n      </Spotlight>,\n    ];\n\n    if (activeSpotlight === null) {\n      return null;\n    }\n    return spotlights[activeSpotlight];\n  };\n\n  return (\n    <SpotlightManager>\n      <SpotlightTarget name=\"comment\">\n        <IconButton icon={CommentAddIcon} label=\"comment\" />\n      </SpotlightTarget>\n      <SpotlightTarget name=\"copy\">\n        <IconButton icon={CopyIcon} label=\"Copy\" />\n      </SpotlightTarget>\n      <Button appearance=\"primary\" onClick={start}>\n        Start tour\n      </Button>\n      <SpotlightTransition>{renderActiveSpotlight()}</SpotlightTransition>\n    </SpotlightManager>\n  );\n};",
+    after: "import React, { useState } from 'react';\nimport Button, { IconButton } from '@atlaskit/button/new';\nimport CommentAddIcon from '@atlaskit/icon/core/comment-add';\nimport CopyIcon from '@atlaskit/icon/core/copy';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport {\n  PopoverContent,\n  PopoverProvider,\n  PopoverTarget,\n  SpotlightActions,\n  SpotlightBody,\n  SpotlightCard,\n  SpotlightControls,\n  SpotlightDismissControl,\n  SpotlightFooter,\n  SpotlightHeader,\n  SpotlightHeadline,\n  SpotlightPrimaryAction,\n  SpotlightSecondaryAction,\n  SpotlightStepCount,\n} from '@atlaskit/spotlight';\n\nconst SpotlightTour = () => {\n  const [currentStep, setCurrentStep] = useState<number>(0);\n\n  const dismiss = () => setCurrentStep(0);\n  const back = () => setCurrentStep(Math.max(currentStep - 1, 1));\n  const next = () => setCurrentStep(Math.min(currentStep + 1, 2));\n  const done = () => setCurrentStep(0);\n\n  return (\n    <>\n      <PopoverProvider>\n        <PopoverTarget>\n          <IconButton icon={CommentAddIcon} label=\"comment\" />\n        </PopoverTarget>\n        <PopoverContent dismiss={dismiss} placement=\"bottom-start\" isVisible={currentStep === 1}>\n          <SpotlightCard>\n            <SpotlightHeader>\n              <SpotlightHeadline>Add a comment</SpotlightHeadline>\n              <SpotlightControls>\n                <SpotlightDismissControl onClick={dismiss} />\n              </SpotlightControls>\n            </SpotlightHeader>\n            <SpotlightBody>\n              <Text>Quickly add a comment to the work item.</Text>\n            </SpotlightBody>\n            <SpotlightFooter>\n              <SpotlightStepCount>1 of 2</SpotlightStepCount>\n              <SpotlightActions>\n                <SpotlightPrimaryAction onClick={next}>Next</SpotlightPrimaryAction>\n              </SpotlightActions>\n            </SpotlightFooter>\n          </SpotlightCard>\n        </PopoverContent>\n      </PopoverProvider>\n\n      <PopoverProvider>\n        <PopoverTarget>\n          <IconButton icon={CopyIcon} label=\"Copy\" />\n        </PopoverTarget>\n        <PopoverContent dismiss={dismiss} placement=\"bottom-start\" isVisible={currentStep === 2}>\n          <SpotlightCard>\n            <SpotlightHeader>\n              <SpotlightHeadline>Copy code</SpotlightHeadline>\n              <SpotlightControls>\n                <SpotlightDismissControl onClick={dismiss} />\n              </SpotlightControls>\n            </SpotlightHeader>\n            <SpotlightBody>\n              <Text>Click to copy the example code to your clipboard.</Text>\n            </SpotlightBody>\n            <SpotlightFooter>\n              <SpotlightStepCount>2 of 2</SpotlightStepCount>\n              <SpotlightActions>\n                <SpotlightSecondaryAction onClick={back}>Back</SpotlightSecondaryAction>\n                <SpotlightPrimaryAction onClick={done}>Done</SpotlightPrimaryAction>\n              </SpotlightActions>\n            </SpotlightFooter>\n          </SpotlightCard>\n        </PopoverContent>\n      </PopoverProvider>\n\n      <Button appearance=\"primary\" onClick={() => setCurrentStep(1)}>\n        Start tour\n      </Button>\n    </>\n  );\n};",
+    explanation: "Key changes when migrating a multi-step spotlight tour:\n- SpotlightManager coordinated multiple spotlights in a tour. PopoverProvider manages internal state for a single spotlight.\n- Each target gets its own PopoverProvider > PopoverTarget > PopoverContent structure\n- The spotlight array pattern is replaced with individual SpotlightCard components per target\n- Control visibility with isVisible={currentStep === n} on each PopoverContent\n- Add SpotlightStepCount component in SpotlightFooter to show progress (e.g., \"1 of 3\")\n- Use SpotlightSecondaryAction for \"Back\" buttons instead of appearance: 'subtle' in the actions array\n- Use SpotlightPrimaryAction for \"Next\" and \"Done\" buttons\n- The renderActiveSpotlight pattern is no longer needed - visibility is controlled declaratively\n- Navigation functions use Math.max/Math.min to bound the step range safely\n- All other migration changes from single step spotlight migration guide apply."
+  }],
+  bestPractices: ['Use a numeric currentStep state where 0 = hidden, 1+ = active step number', 'Always include SpotlightStepCount in multi-step tours for user orientation', 'First step should only have "Next" action, middle steps have "Back" and "Next", last step has "Back" and "Done"', 'Use SpotlightSecondaryAction for back/dismiss actions and SpotlightPrimaryAction for next/done', 'Include SpotlightDismissControl with onClick={dismiss} so users can exit the tour at any point', 'Bound navigation functions with Math.max/Math.min to prevent invalid step values', 'Preference duplicating Spotlight code instead of trying to have a single `@atlaskit/spotlight` instance that conditionally renders content based on step.'],
+  additionalResources: additionalResources
+};

package/dist/cjs/tools/migration-guides/migrations/onboarding-single-step.js

@@ -0,0 +1,23 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.onboardingSingleStep = void 0;
+var additionalResources = 'Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context';
+var onboardingSingleStep = exports.onboardingSingleStep = {
+  id: 'single-step',
+  title: 'Single Step Spotlight Migration',
+  description: 'Use when code ONLY has `Spotlight` from `@atlaskit/onboarding` (no JiraSpotlight)',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate single step spotlight',
+    description: 'Replace SpotlightTarget, and Spotlight with the new compositional @atlaskit/spotlight components',
+    before: "\n// file1.tsx\nimport React, { useState } from 'react';\nimport Button from '@atlaskit/button/new';\nimport { Spotlight } from '@atlaskit/onboarding';\n\nconst OnboardingSpotlight = () => {\n  const [isSpotlightActive, setIsSpotlightActive] = useState(true);\n  const start = () => setIsSpotlightActive(true);\n  const end = () => setIsSpotlightActive(false);\n\n  return (\n\t\t{isSpotlightActive && (\n\t\t\t<Spotlight\n\t\t\t\tdialogPlacement='bottom right'\n\t\t\t\tactions={[\n\t\t\t\t\t{\n\t\t\t\t\t\tonClick: end,\n\t\t\t\t\t\ttext: 'Got it',\n\t\t\t\t\t},\n\t\t\t\t]}\n\t\t\t\theading=\"Feature Heading\"\n\t\t\t\ttarget=\"my-target\"\n\t\t\t>\n\t\t\t\tThis is the spotlight body content describing the feature.\n\t\t\t</Spotlight>\n\t\t)}\n  );\n};\n\n// file2.tsx\nimport React from 'react';\nimport Button from '@atlaskit/button/new';\nimport { Spotlight } from '@atlaskit/onboarding';\n\nconst SomeFeature = () => {\n\n  return (\n\t\t<SpotlightTarget name=\"my-target\">\n\t\t\t<Button>Target Element</Button>\n\t\t</SpotlightTarget>\n  );\n};\n",
+    after: "\n// file2.tsx -- the Spotlight has been co-located to the targeted element.\nimport React, { useState } from 'react';\nimport Button from '@atlaskit/button/new';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport {\n  PopoverContent,\n  PopoverProvider,\n  PopoverTarget,\n  SpotlightActions,\n  SpotlightBody,\n  SpotlightCard,\n  SpotlightControls,\n  SpotlightDismissControl,\n  SpotlightFooter,\n  SpotlightHeader,\n  SpotlightHeadline,\n  SpotlightPrimaryAction,\n} from '@atlaskit/spotlight';\n\nconst Spotlight = () => {\n  const [isVisible, setIsVisible] = useState(false);\n  const dismiss = () => setIsVisible(false);\n  const done = () => setIsVisible(false);\n\n  return (\n    <PopoverProvider>\n      <PopoverTarget>\n        <Button onClick={() => setIsVisible(true)}>Target Element</Button>\n      </PopoverTarget>\n      <PopoverContent dismiss={dismiss} placement=\"bottom-start\" isVisible={isVisible}>\n        <SpotlightCard>\n          <SpotlightHeader>\n            <SpotlightHeadline>Feature Heading</SpotlightHeadline>\n            <SpotlightControls>\n              <SpotlightDismissControl />\n            </SpotlightControls>\n          </SpotlightHeader>\n          <SpotlightBody>\n            <Text>This is the spotlight body content describing the feature.</Text>\n          </SpotlightBody>\n          <SpotlightFooter>\n            <SpotlightActions>\n              <SpotlightPrimaryAction onClick={done}>Got it</SpotlightPrimaryAction>\n            </SpotlightActions>\n          </SpotlightFooter>\n        </SpotlightCard>\n      </PopoverContent>\n    </PopoverProvider>\n  );\n};",
+    explanation: "Key changes when migrating a single step spotlight:\n- Do not use this migration guide for JiraSpotlight. Use 'jira-spotlight' instead.\n- PopoverProvider maintains internal Spotlight state. SpotlightManager coordinated multiple @atlaskit/onboarding usages and is no longer needed.\n- Replace SpotlightTarget with PopoverTarget - wraps the element to highlight\n- Replace Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning\n- The 'heading' prop becomes SpotlightHeadline inside SpotlightHeader\n- The 'actions' array becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)\n- The children content moves into SpotlightBody wrapped with Text component\n- Add SpotlightDismissControl inside SpotlightControls for the close button\n- The 'target' and/or 'targetName' prop is replaced with PopoverTarget directly wrapping the target element\n- The 'dialogPlacement' prop becomes 'placement' on PopoverContent. Mapping: \"top right\" \u2192 \"top-start\", \"top center\" \u2192 \"top\", \"top left\" \u2192 \"top-end\", \"right bottom\" \u2192 \"right-start\", \"right middle\" \u2192 \"right-start | right-end\", \"right top\" \u2192 \"right-end\", \"bottom left\" \u2192 \"bottom-end\", \"bottom center\" \u2192 \"bottom\", \"bottom right\" \u2192 \"bottom-start\", \"left top\" \u2192 \"left-end\", \"left middle\" \u2192 \"left-start | left-end\", \"left bottom\" \u2192 \"left-start\"'"
+  }],
+  bestPractices: ['PopoverTarget should wrap exactly one child element that will be highlighted', 'Always include SpotlightDismissControl for accessibility - allows users to dismiss via close button', 'SpotlightPrimaryAction is required and wraps the main CTA button', 'Wrap body text content in the Text component from @atlaskit/primitives/compiled'],
+  additionalResources: additionalResources
+};