Rename Dev Overlay to Dev Toolbar (#9271)

* Add more dev overlay tests

* Rename Dev Overlay to Dev Toolbar

* Add config option and preferences

* Fix build

* Alias the event names

* Add changeset

.changeset/lemon-crews-juggle.md

@@ -0,0 +1,9 @@
+---
+'astro': major
+---
+
+Renames Dev Overlay to Dev Toolbar
+
+The previously named Dev Overlay is now known as the Astro Dev Toolbar. Additionally what were called Plugins are now Toolbar Apps. This updates our references to reflect.
+
+As there were a lot of APIs that used these names, the existing APIs are left in place, and aliases for the new Toolbar based names are included as well, which is what will be documented. 

packages/astro/e2e/dev-overlay.test.js

@@ -19,14 +19,14 @@ test.describe('Dev Overlay', () => {
 	test('dev overlay exists in the page', async ({ page, astro }) => {
 		await page.goto(astro.resolveUrl('/'));
 
-		const devOVerlay = page.locator('astro-dev-overlay');
+		const devOVerlay = page.locator('astro-dev-toolbar');
 		await expect(devOVerlay).toHaveCount(1);
 	});
 
 	test('shows plugin name on hover', async ({ page, astro }) => {
 		await page.goto(astro.resolveUrl('/'));
 
-		const overlay = page.locator('astro-dev-overlay');
+		const overlay = page.locator('astro-dev-toolbar');
 		const pluginButton = overlay.locator('button[data-plugin-id="astro"]');
 		const pluginButtonTooltip = pluginButton.locator('.item-tooltip');
 		await pluginButton.hover();
@@ -37,14 +37,14 @@ test.describe('Dev Overlay', () => {
 	test('can open Astro plugin', async ({ page, astro }) => {
 		await page.goto(astro.resolveUrl('/'));
 
-		const overlay = page.locator('astro-dev-overlay');
+		const overlay = page.locator('astro-dev-toolbar');
 		const pluginButton = overlay.locator('button[data-plugin-id="astro"]');
 		await pluginButton.click();
 
 		const astroPluginCanvas = overlay.locator(
-			'astro-dev-overlay-plugin-canvas[data-plugin-id="astro"]'
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro"]'
 		);
-		const astroWindow = astroPluginCanvas.locator('astro-dev-overlay-window');
+		const astroWindow = astroPluginCanvas.locator('astro-dev-toolbar-window');
 		await expect(astroWindow).toHaveCount(1);
 		await expect(astroWindow).toBeVisible();
 
@@ -56,18 +56,18 @@ test.describe('Dev Overlay', () => {
 	test('xray shows highlights and tooltips', async ({ page, astro }) => {
 		await page.goto(astro.resolveUrl('/'));
 
-		const overlay = page.locator('astro-dev-overlay');
+		const overlay = page.locator('astro-dev-toolbar');
 		const pluginButton = overlay.locator('button[data-plugin-id="astro:xray"]');
 		await pluginButton.click();
 
 		const xrayCanvas = overlay.locator(
-			'astro-dev-overlay-plugin-canvas[data-plugin-id="astro:xray"]'
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro:xray"]'
 		);
-		const xrayHighlight = xrayCanvas.locator('astro-dev-overlay-highlight');
+		const xrayHighlight = xrayCanvas.locator('astro-dev-toolbar-highlight');
 		await expect(xrayHighlight).toBeVisible();
 
 		await xrayHighlight.hover();
-		const xrayHighlightTooltip = xrayHighlight.locator('astro-dev-overlay-tooltip');
+		const xrayHighlightTooltip = xrayHighlight.locator('astro-dev-toolbar-tooltip');
 		await expect(xrayHighlightTooltip).toBeVisible();
 
 		// Toggle plugin off
@@ -76,21 +76,41 @@ test.describe('Dev Overlay', () => {
 		await expect(xrayHighlightTooltip).not.toBeVisible();
 	});
 
+	test('xray shows no islands message when there are none', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/xray-no-islands'));
+
+		const overlay = page.locator('astro-dev-toolbar');
+		const pluginButton = overlay.locator('button[data-plugin-id="astro:xray"]');
+		await pluginButton.click();
+
+		const xrayCanvas = overlay.locator(
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro:xray"]'
+		);
+		const auditHighlight = xrayCanvas.locator('astro-dev-toolbar-highlight');
+		await expect(auditHighlight).not.toBeVisible();
+
+		const xrayWindow = xrayCanvas.locator('astro-dev-toolbar-window');
+		await expect(xrayWindow).toHaveCount(1);
+		await expect(xrayWindow).toBeVisible();
+
+		await expect(xrayWindow.locator('astro-dev-toolbar-icon[icon=lightbulb]')).toBeVisible();
+	});
+
 	test('audit shows higlights and tooltips', async ({ page, astro }) => {
 		await page.goto(astro.resolveUrl('/'));
 
-		const overlay = page.locator('astro-dev-overlay');
+		const overlay = page.locator('astro-dev-toolbar');
 		const pluginButton = overlay.locator('button[data-plugin-id="astro:audit"]');
 		await pluginButton.click();
 
 		const auditCanvas = overlay.locator(
-			'astro-dev-overlay-plugin-canvas[data-plugin-id="astro:audit"]'
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro:audit"]'
 		);
-		const auditHighlight = auditCanvas.locator('astro-dev-overlay-highlight');
+		const auditHighlight = auditCanvas.locator('astro-dev-toolbar-highlight');
 		await expect(auditHighlight).toBeVisible();
 
 		await auditHighlight.hover();
-		const auditHighlightTooltip = auditHighlight.locator('astro-dev-overlay-tooltip');
+		const auditHighlightTooltip = auditHighlight.locator('astro-dev-toolbar-tooltip');
 		await expect(auditHighlightTooltip).toBeVisible();
 
 		// Toggle plugin off
@@ -99,22 +119,88 @@ test.describe('Dev Overlay', () => {
 		await expect(auditHighlightTooltip).not.toBeVisible();
 	});
 
+	test('audit shows no issues message when there are no issues', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/audit-no-warning'));
+
+		const overlay = page.locator('astro-dev-toolbar');
+		const pluginButton = overlay.locator('button[data-plugin-id="astro:audit"]');
+		await pluginButton.click();
+
+		const auditCanvas = overlay.locator(
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro:audit"]'
+		);
+		const auditHighlight = auditCanvas.locator('astro-dev-toolbar-highlight');
+		await expect(auditHighlight).not.toBeVisible();
+
+		const auditWindow = auditCanvas.locator('astro-dev-toolbar-window');
+		await expect(auditWindow).toHaveCount(1);
+		await expect(auditWindow).toBeVisible();
+
+		await expect(auditWindow.locator('astro-dev-toolbar-icon[icon=check-circle]')).toBeVisible();
+	});
+
 	test('can open Settings plugin', async ({ page, astro }) => {
 		await page.goto(astro.resolveUrl('/'));
 
-		const overlay = page.locator('astro-dev-overlay');
+		const overlay = page.locator('astro-dev-toolbar');
 		const pluginButton = overlay.locator('button[data-plugin-id="astro:settings"]');
 		await pluginButton.click();
 
 		const settingsPluginCanvas = overlay.locator(
-			'astro-dev-overlay-plugin-canvas[data-plugin-id="astro:settings"]'
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro:settings"]'
 		);
-		const settingsWindow = settingsPluginCanvas.locator('astro-dev-overlay-window');
+		const settingsWindow = settingsPluginCanvas.locator('astro-dev-toolbar-window');
 		await expect(settingsWindow).toHaveCount(1);
 		await expect(settingsWindow).toBeVisible();
 
 		// Toggle plugin off
 		await pluginButton.click();
 		await expect(settingsWindow).not.toBeVisible();
 	});
+
+	test('Opening a plugin closes the currently opened plugin', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+
+		const overlay = page.locator('astro-dev-toolbar');
+		let pluginButton = overlay.locator('button[data-plugin-id="astro:settings"]');
+		await pluginButton.click();
+
+		const settingsPluginCanvas = overlay.locator(
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro:settings"]'
+		);
+		const settingsWindow = settingsPluginCanvas.locator('astro-dev-toolbar-window');
+		await expect(settingsWindow).toHaveCount(1);
+		await expect(settingsWindow).toBeVisible();
+
+		// Click the astro plugin
+		pluginButton = overlay.locator('button[data-plugin-id="astro"]');
+		await pluginButton.click();
+
+		const astroPluginCanvas = overlay.locator(
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro"]'
+		);
+		const astroWindow = astroPluginCanvas.locator('astro-dev-toolbar-window');
+		await expect(astroWindow).toHaveCount(1);
+		await expect(astroWindow).toBeVisible();
+
+		await expect(settingsWindow).not.toBeVisible();
+	});
+
+	test('Settings plugin contains message on disabling the overlay', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+
+		const overlay = page.locator('astro-dev-toolbar');
+		let pluginButton = overlay.locator('button[data-plugin-id="astro:settings"]');
+		await pluginButton.click();
+
+		const settingsPluginCanvas = overlay.locator(
+			'astro-dev-toolbar-plugin-canvas[data-plugin-id="astro:settings"]'
+		);
+		const settingsWindow = settingsPluginCanvas.locator('astro-dev-toolbar-window');
+		await expect(settingsWindow).toHaveCount(1);
+		await expect(settingsWindow).toBeVisible();
+
+		const hideOverlay = settingsWindow.getByRole('heading', { name: 'Hide overlay' });
+		await expect(hideOverlay).toBeVisible();
+	});
 });

packages/astro/e2e/fixtures/dev-overlay/src/pages/audit-no-warning.astro

@@ -0,0 +1,5 @@
+---
+
+---
+
+<img src="https://astro.build/assets/press/astro-logo-dark.svg" alt="Astro logo" />

packages/astro/e2e/fixtures/dev-overlay/src/pages/xray-no-islands.astro

@@ -0,0 +1,5 @@
+---
+
+---
+
+<div>no islands on this page</div>

packages/astro/src/@types/astro.ts

@@ -1159,6 +1159,7 @@ export interface AstroUserConfig {
 	 * @docs
 	 * @kind heading
 	 * @name Dev Overlay Options
+	 * @deprecated Use `devToolbar` instead.
 	 */
 	devOverlay?: {
 		/**
@@ -1183,6 +1184,34 @@ export interface AstroUserConfig {
 		defaultState: 'minimized' | 'expanded';
 	};
 
+	/**
+	 * @docs
+	 * @kind heading
+	 * @name Dev Toolbar Options
+	 */
+	devToolbar?: {
+		/**
+		 * @docs
+		 * @name devToolbar.enabled
+		 * @type {boolean}
+		 * @default `true`
+		 * @description
+		 * Whether to enable the Astro Dev Toolbar. This toolbar allows you to inspect your page islands, see helpful audits on performance and accessibility, and more.
+		 *
+		 * This option is scoped to the entire project, to only disable the toolbar for yourself, run `npm run astro preferences disable devToolbar`. To disable the toolbar for all your Astro projects, run `npm run astro preferences disable devToolbar --global`.
+		 */
+		enabled: boolean;
+		/**
+		 * @docs
+		 * @name devToolbar.defaultState
+		 * @type {'minimized' | 'expanded'}
+		 * @default `minimized`
+		 * @description
+		 * Whether the Dev Toolbar should be expanded or minimized by default.
+		 */
+		defaultState: 'minimized' | 'expanded';
+	};
+
 	/**
 	 * @docs
 	 * @kind heading
@@ -1716,7 +1745,7 @@ export interface AstroSettings {
 	 * Map of directive name (e.g. `load`) to the directive script code
 	 */
 	clientDirectives: Map<string, string>;
-	devOverlayPlugins: string[];
+	devToolbarApps: string[];
 	middlewares: { pre: string[]; post: string[] };
 	tsConfig: TSConfig | undefined;
 	tsConfigPath: string | undefined;
@@ -2292,7 +2321,11 @@ export interface AstroIntegration {
 			injectScript: (stage: InjectedScriptStage, content: string) => void;
 			injectRoute: (injectRoute: InjectedRoute) => void;
 			addClientDirective: (directive: ClientDirectiveConfig) => void;
+			/**
+			 * @deprecated Use `addDevToolbarApp` instead.
+			 */
 			addDevOverlayPlugin: (entrypoint: string) => void;
+			addDevToolbarApp: (entrypoint: string) => void;
 			addMiddleware: (mid: AstroIntegrationMiddleware) => void;
 			logger: AstroIntegrationLogger;
 			// TODO: Add support for `injectElement()` for full HTML element injection, not just scripts.
@@ -2563,6 +2596,18 @@ export type DevOverlayMetadata = Window &
 
 declare global {
 	interface HTMLElementTagNameMap {
+		'astro-dev-toolbar': AstroDevOverlay;
+		'astro-dev-toolbar-window': DevOverlayWindow;
+		'astro-dev-toolbar-plugin-canvas': DevOverlayCanvas;
+		'astro-dev-toolbar-tooltip': DevOverlayTooltip;
+		'astro-dev-toolbar-highlight': DevOverlayHighlight;
+		'astro-dev-toolbar-toggle': DevOverlayToggle;
+		'astro-dev-toolbar-badge': DevOverlayBadge;
+		'astro-dev-toolbar-button': DevOverlayButton;
+		'astro-dev-toolbar-icon': DevOverlayIcon;
+		'astro-dev-toolbar-card': DevOverlayCard;
+
+		// Deprecated names
 		'astro-dev-overlay': AstroDevOverlay;
 		'astro-dev-overlay-window': DevOverlayWindow;
 		'astro-dev-overlay-plugin-canvas': DevOverlayCanvas;

packages/astro/src/core/config/schema.ts

@@ -45,6 +45,10 @@ const ASTRO_CONFIG_DEFAULTS = {
 		enabled: true,
 		defaultState: 'minimized',
 	},
+	devToolbar: {
+		enabled: true,
+		defaultState: 'minimized',
+	},
 	compressHTML: true,
 	server: {
 		host: false,
@@ -236,6 +240,14 @@ export const AstroConfigSchema = z.object({
 				.default(ASTRO_CONFIG_DEFAULTS.devOverlay.defaultState),
 		})
 		.default(ASTRO_CONFIG_DEFAULTS.devOverlay),
+	devToolbar: z
+		.object({
+			enabled: z.boolean().default(ASTRO_CONFIG_DEFAULTS.devToolbar.enabled),
+			defaultState: z
+				.enum(['minimized', 'expanded'])
+				.default(ASTRO_CONFIG_DEFAULTS.devToolbar.defaultState),
+		})
+		.default(ASTRO_CONFIG_DEFAULTS.devToolbar),
 	markdown: z
 		.object({
 			syntaxHighlight: z

packages/astro/src/core/config/settings.ts

@@ -102,7 +102,7 @@ export function createBaseSettings(config: AstroConfig): AstroSettings {
 		clientDirectives: getDefaultClientDirectives(),
 		middlewares: { pre: [], post: [] },
 		watchFiles: [],
-		devOverlayPlugins: [],
+		devToolbarApps: [],
 		timer: new AstroTimer(),
 	};
 }

packages/astro/src/integrations/index.ts

@@ -141,7 +141,11 @@ export async function runHookConfigSetup({
 					updatedSettings.watchFiles.push(path instanceof URL ? fileURLToPath(path) : path);
 				},
 				addDevOverlayPlugin: (entrypoint) => {
-					updatedSettings.devOverlayPlugins.push(entrypoint);
+					// TODO add a deprecation warning in Astro 5.
+					hooks.addDevToolbarApp(entrypoint);
+				},
+				addDevToolbarApp: (entrypoint) => {
+					updatedSettings.devToolbarApps.push(entrypoint);
 				},
 				addClientDirective: ({ name, entrypoint }) => {
 					if (updatedSettings.clientDirectives.has(name) || addedClientDirectives.has(name)) {

packages/astro/src/preferences/defaults.ts

@@ -1,5 +1,5 @@
 export const DEFAULT_PREFERENCES = {
-	devOverlay: {
+	devToolbar: {
 		/** Specifies whether the user has the Dev Overlay enabled */
 		enabled: true,
 	},