[9.2] [SharedUX] Add kbn-tour-queue package to avoid tour overlapping (elastic#242640) (elastic#243754)

# Backport

This will backport the following commits from `main` to `9.2`:
- [[SharedUX] Add kbn-tour-queue package to avoid tour overlapping
(elastic#242640)](elastic#242640)

<!--- Backport version: 10.2.0 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Ángeles Martínez
Barrio","email":"[email protected]"},"sourceCommit":{"committedDate":"2025-11-20T16:30:43Z","message":"[SharedUX]
Add kbn-tour-queue package to avoid tour overlapping (elastic#242640)\n\nCloses
https://github.com/elastic/kibana-team/issues/2146\n\n## Summary\n\n-
This PR introduces a new package to orchestrate tours to
avoid\noverlapping. Currently, Side Nav Tour and Security tour are
overlapping\nin this way:\n\n<img width=\"675\" height=\"391\"
alt=\"Screenshot 2025-11-12 at 10 32
34\"\nsrc=\"https://github.com/user-attachments/assets/27a3ba52-2c69-4fe0-bf62-18d649354de5\"\n/>\n\n-
Package `kbn-tour-queue` uses `globalThis` to share state
across\nplugins and to ensure only one single instance of the state
manager is\nused. This approach is based on @Dosant
`kbn-developer-toolbar`
[state\nimplementation](https://github.com/elastic/kibana/blob/7518eebd9acaf352f02241901cbeb7129e0a1f32/src/platform/packages/shared/kbn-developer-toolbar/src/hooks/use_toolbar_state.tsx#L14-L40).\n-
If any of the tours in the queue are skipped, the remaining tours
are\nalso skipped (currently only Side Nav tour handles skip
behaviour).\nSkipped status is not persisted for now, it is only honored
until page\nreload.\n- Side Nav and Security tours were updated to use
the new tour queue\nsystem.\n\n### Testing\n\nTour completion (Spaces +
SideNav +
Security):\n\n\nhttps://github.com/user-attachments/assets/139847ac-48ea-41e6-8eba-cf5c4981ed96\n\nTour
skipping (Spaces +
SideNav):\n\n\nhttps://github.com/user-attachments/assets/e75f7aa0-6cb4-4c43-9117-172f88f1fe8b","sha":"60952a0bbdeb09c931eaf4469c01f21931836651","branchLabelMapping":{"^v9.3.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","Team:SharedUX","backport:version","v9.3.0","v9.2.2"],"title":"[SharedUX]
Add kbn-tour-queue package to avoid tour
overlapping","number":242640,"url":"https://github.com/elastic/kibana/pull/242640","mergeCommit":{"message":"[SharedUX]
Add kbn-tour-queue package to avoid tour overlapping (elastic#242640)\n\nCloses
https://github.com/elastic/kibana-team/issues/2146\n\n## Summary\n\n-
This PR introduces a new package to orchestrate tours to
avoid\noverlapping. Currently, Side Nav Tour and Security tour are
overlapping\nin this way:\n\n<img width=\"675\" height=\"391\"
alt=\"Screenshot 2025-11-12 at 10 32
34\"\nsrc=\"https://github.com/user-attachments/assets/27a3ba52-2c69-4fe0-bf62-18d649354de5\"\n/>\n\n-
Package `kbn-tour-queue` uses `globalThis` to share state
across\nplugins and to ensure only one single instance of the state
manager is\nused. This approach is based on @Dosant
`kbn-developer-toolbar`
[state\nimplementation](https://github.com/elastic/kibana/blob/7518eebd9acaf352f02241901cbeb7129e0a1f32/src/platform/packages/shared/kbn-developer-toolbar/src/hooks/use_toolbar_state.tsx#L14-L40).\n-
If any of the tours in the queue are skipped, the remaining tours
are\nalso skipped (currently only Side Nav tour handles skip
behaviour).\nSkipped status is not persisted for now, it is only honored
until page\nreload.\n- Side Nav and Security tours were updated to use
the new tour queue\nsystem.\n\n### Testing\n\nTour completion (Spaces +
SideNav +
Security):\n\n\nhttps://github.com/user-attachments/assets/139847ac-48ea-41e6-8eba-cf5c4981ed96\n\nTour
skipping (Spaces +
SideNav):\n\n\nhttps://github.com/user-attachments/assets/e75f7aa0-6cb4-4c43-9117-172f88f1fe8b","sha":"60952a0bbdeb09c931eaf4469c01f21931836651"}},"sourceBranch":"main","suggestedTargetBranches":["9.2"],"targetPullRequestStates":[{"branch":"main","label":"v9.3.0","branchLabelMappingKey":"^v9.3.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/242640","number":242640,"mergeCommit":{"message":"[SharedUX]
Add kbn-tour-queue package to avoid tour overlapping (elastic#242640)\n\nCloses
https://github.com/elastic/kibana-team/issues/2146\n\n## Summary\n\n-
This PR introduces a new package to orchestrate tours to
avoid\noverlapping. Currently, Side Nav Tour and Security tour are
overlapping\nin this way:\n\n<img width=\"675\" height=\"391\"
alt=\"Screenshot 2025-11-12 at 10 32
34\"\nsrc=\"https://github.com/user-attachments/assets/27a3ba52-2c69-4fe0-bf62-18d649354de5\"\n/>\n\n-
Package `kbn-tour-queue` uses `globalThis` to share state
across\nplugins and to ensure only one single instance of the state
manager is\nused. This approach is based on @Dosant
`kbn-developer-toolbar`
[state\nimplementation](https://github.com/elastic/kibana/blob/7518eebd9acaf352f02241901cbeb7129e0a1f32/src/platform/packages/shared/kbn-developer-toolbar/src/hooks/use_toolbar_state.tsx#L14-L40).\n-
If any of the tours in the queue are skipped, the remaining tours
are\nalso skipped (currently only Side Nav tour handles skip
behaviour).\nSkipped status is not persisted for now, it is only honored
until page\nreload.\n- Side Nav and Security tours were updated to use
the new tour queue\nsystem.\n\n### Testing\n\nTour completion (Spaces +
SideNav +
Security):\n\n\nhttps://github.com/user-attachments/assets/139847ac-48ea-41e6-8eba-cf5c4981ed96\n\nTour
skipping (Spaces +
SideNav):\n\n\nhttps://github.com/user-attachments/assets/e75f7aa0-6cb4-4c43-9117-172f88f1fe8b","sha":"60952a0bbdeb09c931eaf4469c01f21931836651"}},{"branch":"9.2","label":"v9.2.2","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Author: angeles-mb

.github/CODEOWNERS

@@ -595,6 +595,7 @@ src/platform/packages/shared/kbn-test-jest-helpers @elastic/kibana-operations @e
 src/platform/packages/shared/kbn-test-subj-selector @elastic/kibana-operations @elastic/appex-qa
 src/platform/packages/shared/kbn-timerange @elastic/obs-onboarding-team
 src/platform/packages/shared/kbn-tooling-log @elastic/kibana-operations
+src/platform/packages/shared/kbn-tour-queue @elastic/appex-sharedux
 src/platform/packages/shared/kbn-traced-es-client @elastic/observability-ui
 src/platform/packages/shared/kbn-tracing @elastic/kibana-core @elastic/obs-ai-assistant
 src/platform/packages/shared/kbn-tracing-config @elastic/kibana-core

package.json

@@ -1058,6 +1058,7 @@
     "@kbn/timelion-grammar": "link:src/platform/packages/private/kbn-timelion-grammar",
     "@kbn/timerange": "link:src/platform/packages/shared/kbn-timerange",
     "@kbn/tinymath": "link:src/platform/packages/private/kbn-tinymath",
+    "@kbn/tour-queue": "link:src/platform/packages/shared/kbn-tour-queue",
     "@kbn/traced-es-client": "link:src/platform/packages/shared/kbn-traced-es-client",
     "@kbn/tracing": "link:src/platform/packages/shared/kbn-tracing",
     "@kbn/tracing-config": "link:src/platform/packages/shared/kbn-tracing-config",

packages/kbn-optimizer/limits.yml

@@ -106,7 +106,7 @@ pageLoadAssetSize:
   ml: 89000
   mockIdpPlugin: 7544
   monitoring: 28983
-  navigation: 13598
+  navigation: 14742
   newsfeed: 12371
   noDataPage: 1749
   observability: 176467

src/platform/packages/shared/kbn-tour-queue/README.md

@@ -0,0 +1,33 @@
+# @kbn/tour-queue
+
+# Tour Queue
+
+A global queue mechanism for managing sequential tour display across Kibana plugins.
+
+## API
+
+### useTourQueue(tourId: TourId)
+
+Hook that manages tour registration and state.
+
+**Returns:**
+- `isActive: boolean` - Whether this tour should be shown
+- `onComplete: () => void` - Callback to mark tour as completed
+
+### Tour Object Methods
+
+When you register a tour, you get a tour object with these methods:
+
+- `isActive()` - Check if this tour is currently active
+- `complete()` - Mark tour as completed
+- `skip()` - Skip all remaining tours for current page load
+- `unregister()` - Remove tour from queue (cleanup)
+
+### Tour Order
+
+| Order | Tour ID | Description |
+|----------|---------|-------------|
+| 1 | `solutionNavigationTour` | Solution navigation tour (Navigation plugin) |
+| 2 | `siemMigrationSetupTour` | Security SIEM migration setup (Security plugin) |
+
+**Note:** Lower order = shown first. If a tour is skipped, all remaining tours are skipped for the current page load only. Currently, only the navigation tour implements skip functionality.

src/platform/packages/shared/kbn-tour-queue/hooks/use_tour_queue.test.ts

@@ -0,0 +1,86 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { renderHook, act } from '@testing-library/react';
+import { useTourQueue } from './use_tour_queue';
+import { getTourQueue } from '../state/registry';
+import type { TourId } from '..';
+
+describe('useTourQueue', () => {
+  const REGISTRY_KEY = '__KIBANA_TOUR_QUEUE_CTX__';
+
+  const TOUR_1 = 'tour1' as TourId;
+  const TOUR_2 = 'tour2' as TourId;
+
+  beforeEach(() => {
+    // Clean up the global registry before each test
+    if (typeof globalThis !== 'undefined') {
+      delete (globalThis as any)[REGISTRY_KEY];
+    }
+  });
+
+  it('should return isActive as true for the active tour', () => {
+    const { result } = renderHook(() => useTourQueue(TOUR_1));
+
+    expect(result.current.isActive).toBe(true);
+  });
+
+  it('should return isActive as false for a waiting tour', () => {
+    renderHook(() => useTourQueue(TOUR_1));
+    const tour2Hook = renderHook(() => useTourQueue(TOUR_2));
+
+    expect(tour2Hook.result.current.isActive).toBe(false);
+  });
+
+  it('should update isActive when the tour becomes active', () => {
+    const tour1Hook = renderHook(() => useTourQueue(TOUR_1));
+    const tour2Hook = renderHook(() => useTourQueue(TOUR_2));
+
+    expect(tour2Hook.result.current.isActive).toBe(false);
+
+    // Complete the first tour
+    act(() => {
+      tour1Hook.result.current.onComplete();
+    });
+
+    // Second tour should now be active
+    expect(tour2Hook.result.current.isActive).toBe(true);
+  });
+
+  it('should update isActive to false when tour is completed', () => {
+    const { result } = renderHook(() => useTourQueue(TOUR_1));
+
+    expect(result.current.isActive).toBe(true);
+
+    act(() => {
+      result.current.onComplete();
+    });
+
+    expect(result.current.isActive).toBe(false);
+  });
+
+  it('should update isActive to false when queue is skipped', () => {
+    const tour1Hook = renderHook(() => useTourQueue(TOUR_1));
+    const tour2Hook = renderHook(() => useTourQueue(TOUR_2));
+    const tourQueue = getTourQueue();
+
+    // Initial state
+    expect(tour1Hook.result.current.isActive).toBe(true);
+    expect(tour2Hook.result.current.isActive).toBe(false);
+
+    // Skip all tours
+    act(() => {
+      tourQueue.skipAll();
+    });
+
+    // All tours should be false
+    expect(tour1Hook.result.current.isActive).toBe(false);
+    expect(tour2Hook.result.current.isActive).toBe(false);
+  });
+});

src/platform/packages/shared/kbn-tour-queue/hooks/use_tour_queue.ts

@@ -0,0 +1,64 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getTourQueue } from '../state/registry';
+import type { TourId } from '..';
+import type { Tour } from '../state/tour_queue_state';
+
+/**
+ * Result object returned by useTourQueue
+ * @public
+ */
+export interface TourQueueResult {
+  /** Whether this tour is currently active and should be shown */
+  isActive: boolean;
+  /** Callback to mark this tour as completed */
+  onComplete: () => void;
+}
+
+/**
+ * Hook to manage tour queue state for a specific tour.
+ * Automatically registers the tour, subscribes to queue changes,
+ * and handles cleanup on unmount.
+ *
+ * @param tourId - The ID of the tour. Must be a valid ID from {@link TOURS}
+ * @returns Object containing isActive state and onComplete callback
+ * @public
+ */
+export const useTourQueue = (tourId: TourId): TourQueueResult => {
+  const tourQueue = getTourQueue();
+  const [isActive, setIsActive] = useState(false);
+  const tourRef = useRef<Tour | null>(null);
+
+  useEffect(() => {
+    // Register and get tour object
+    const tour = tourQueue.register(tourId);
+    tourRef.current = tour;
+    // Set initial isActive state
+    setIsActive(tour.isActive());
+    // Subscribe to state changes and get cleanup function
+    const stopListening = tourQueue.subscribe(() => {
+      setIsActive(tour.isActive());
+    });
+    return () => {
+      tourRef.current?.unregister();
+      stopListening();
+    };
+  }, [tourId, tourQueue]);
+
+  const onComplete = useCallback(() => {
+    tourRef.current?.complete();
+  }, []);
+
+  return {
+    isActive,
+    onComplete,
+  };
+};

src/platform/packages/shared/kbn-tour-queue/index.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+export { useTourQueue } from './hooks/use_tour_queue';
+export { getTourQueue } from './state/registry';
+export type { TourQueueResult } from './hooks/use_tour_queue';
+export type { Tour } from './state/tour_queue_state';
+
+const TOUR_REGISTRY = {
+  solutionNavigationTour: 1,
+  siemMigrationSetupTour: 2,
+} as const;
+
+/**
+ * Valid tour IDs for registering tours in the queue.
+ * Tours are shown in order based on their registry value.
+ * @public
+ */
+export const TOURS = {
+  NAVIGATION: 'solutionNavigationTour',
+  SECURITY_SIEM_MIGRATION: 'siemMigrationSetupTour',
+} as const;
+
+/**
+ * Union type of all available tour IDs
+ * @public
+ */
+export type TourId = (typeof TOURS)[keyof typeof TOURS];
+
+/**
+ * Get the display order for a tour. Lower numbers are shown first.
+ * @param tourId - The tour ID
+ * @returns The numeric order value for the tour
+ * @internal
+ */
+export const getOrder = (tourId: TourId): number => {
+  return TOUR_REGISTRY[tourId];
+};

src/platform/packages/shared/kbn-tour-queue/jest.config.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+module.exports = {
+  preset: '@kbn/test',
+  rootDir: '../../../../..',
+  roots: ['<rootDir>/src/platform/packages/shared/kbn-tour-queue'],
+};

src/platform/packages/shared/kbn-tour-queue/kibana.jsonc

@@ -0,0 +1,7 @@
+{
+  "type": "shared-browser",
+  "id": "@kbn/tour-queue",
+  "owner": "@elastic/appex-sharedux",
+  "group": "platform",
+  "visibility": "shared"
+}

src/platform/packages/shared/kbn-tour-queue/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@kbn/tour-queue",
+  "private": true,
+  "version": "1.0.0",
+  "license": "Elastic License 2.0 OR AGPL-3.0-only OR SSPL-1.0",
+  "sideEffects": false
+}