From dbd59aaf5b8b12c7bd5812c23e45ed285b19c0b3 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 1 Dec 2023 15:45:21 -0500 Subject: [PATCH 01/11] Rename Dev Overlay to Dev Toolbar --- ...ence.mdx => dev-toolbar-app-reference.mdx} | 148 +++++++++--------- src/i18n/en/nav.ts | 6 +- vercel.json | 5 +- 3 files changed, 81 insertions(+), 78 deletions(-) rename src/content/docs/en/reference/{dev-overlay-plugin-reference.mdx => dev-toolbar-app-reference.mdx} (51%) diff --git a/src/content/docs/en/reference/dev-overlay-plugin-reference.mdx b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx similarity index 51% rename from src/content/docs/en/reference/dev-overlay-plugin-reference.mdx rename to src/content/docs/en/reference/dev-toolbar-app-reference.mdx index 48cb699a345c5..c492cbdea0a44 100644 --- a/src/content/docs/en/reference/dev-overlay-plugin-reference.mdx +++ b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx @@ -1,17 +1,17 @@ --- -title: Dev Overlay Plugin API +title: Dev Toolbar App API i18nReady: false --- -The Astro Dev Overlay Plugin API allows you to create plugins that can be used to extend the Astro Dev Overlay. This allows you to add new features and integrations with third-party services. +The Astro Dev Toolbar App API allows you to create apps that can be used to extend the Astro Dev Toolbar. This allows you to add new features and integrations with third-party services. :::note This API is currently **experimental**. It is subject to change in future releases with no prior notice. ::: -## Adding plugins +## Adding apps -[Astro Integrations](/en/reference/configuration-reference/#integrations) can add plugins in [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup) using the `addDevOverlayPlugin` method. +[Astro Integrations](/en/reference/configuration-reference/#integrations) can add apps in [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup) using the `addDevToolbarApp` method. ```ts title="integrations.js" /** @@ -20,25 +20,25 @@ This API is currently **experimental**. It is subject to change in future releas export default () => ({ name: "my-integration", hooks: { - "astro:config:setup": ({ addDevOverlayPlugin }) => { - addDevOverlayPlugin("./my-plugin.js"); + "astro:config:setup": ({ addDevToolbarApp }) => { + addDevToolbarApp("./my-app.js"); }, }, }); ``` -## Structure of a plugin +## Structure of a Dev Toolbar App -A plugin is a `.js` or `.ts` file that default exports an object with the following required properties: +A Dev Toolbar App is a `.js` or `.ts` file that default exports an object with the following required properties: -```ts title="src/my-plugin.js" +```ts title="src/my-app.js" export default { - id: 'super-plugin', - name: 'My Super Plugin', + id: 'super-app', + name: 'My Super App', icon: '...', init(canvas, eventTarget) { eventTarget.dispatchEvent( - new CustomEvent('plugin-notification', { + new CustomEvent('app-notification', { detail: { state: true, }, @@ -51,32 +51,32 @@ export default { ### `id: string` -A unique identifier for the plugin. This will be used to uniquely identify the plugin in hooks and events. +A unique identifier for the app. This will be used to uniquely identify the app in hooks and events. -```ts title="src/my-plugin.js" {2} +```ts title="src/my-app.js" {2} export default { - id: 'my-plugin', + id: 'my-app', // ... } ``` ### `name: string` -The name of the plugin. This will be shown to users whenever the plugin needs to be referenced using a human-readable name. +The name of the app. This will be shown to users whenever the app needs to be referenced using a human-readable name. -```ts title="src/my-plugin.js" {2} +```ts title="src/my-app.js" {2} export default { // ... - name: 'My Plugin', + name: 'My App', // ... } ``` ### `icon: Icon` -The icon of the plugin. This will be used to display the plugin in the UI. This can either be an icon from [the icon list](#icons), or a string containing the SVG markup of the icon. +The icon of the app. This will be used to display the app in the UI. This can either be an icon from [the icon list](#icons), or a string containing the SVG markup of the icon. -```ts title="src/my-plugin.js" {2} +```ts title="src/my-app.js" {2} export default { // ... icon: '...', // or 'astro:logo' @@ -85,18 +85,18 @@ export default { ### `init: (canvas: ShadowRoot, eventTarget: EventTarget) => void` -This is the core part of the plugin. This function will be called when the plugin is loaded, which will either be when the browser is idle or when the user clicks on the plugin in the UI. +This is the core part of the app. This function will be called when the app is loaded, which will either be when the browser is idle or when the user clicks on the app in the UI. The function receives two arguments: #### `canvas` -A ShadowRoot that the plugin can use to render its UI. Every plugin receive its own dedicated ShadowRoot for rendering its UI. Additionally, the parent element is positioned using `position: absolute;` and as such, the plugin UI automatically won't affect the layout of the page. +A ShadowRoot that the app can use to render its UI. Every app receive its own dedicated ShadowRoot for rendering its UI. Additionally, the parent element is positioned using `position: absolute;` and as such, the app UI automatically won't affect the layout of the page. ```ts export default { - id: 'super-plugin', - name: 'My Super Plugin', + id: 'super-app', + name: 'My Super App', icon: '...', init(canvas) { canvas.appendChild(document.createTextNode('Hello World!')) @@ -106,19 +106,19 @@ export default { #### `eventTarget` -An [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) that can be used to send and receive events from the dev overlay. +An [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) that can be used to send and receive events from the Dev Toolbar. ### `beforeTogglingOff` -This optional function will be called when the user clicks on the plugin icon in the UI to toggle off the plugin. This function can be used, for example, to perform cleanup operations, do an animation, or to ask the user for confirmation before toggling off the plugin. +This optional function will be called when the user clicks on the app icon in the UI to toggle off the app. This function can be used, for example, to perform cleanup operations, do an animation, or to ask the user for confirmation before toggling off the app. -If a falsy value is returned, the toggling off will be cancelled and the plugin will stay enabled. +If a falsy value is returned, the toggling off will be cancelled and the app will stay enabled. -```ts title="src/my-plugin.js" {2} +```ts title="src/my-app.js" {2} export default { // ... beforeTogglingOff() { - const confirmation = window.confirm('Are you sure you want to disable this plugin?'); + const confirmation = window.confirm('Are you sure you want to disable this app?'); return confirmation; } } @@ -126,23 +126,23 @@ export default { #### canvas -The ShadowRoot of the plugin, can be used to render any UI needed. +The ShadowRoot of the app, can be used to render any UI needed. ## Client-side Events -Using the [`eventTarget`](#eventtarget) argument on the [`init`](#init-canvas-shadowroot-eventtarget-eventtarget--void) hook, plugins can send and receive events from the dev overlay. The following events are available: +Using the [`eventTarget`](#eventtarget) argument on the [`init`](#init-canvas-shadowroot-eventtarget-eventtarget--void) hook, apps can send and receive events from the Dev Toolbar. The following events are available: -### `plugin-toggled` +### `app-toggled` -This event is fired when the user clicks on the plugin icon in the dev overlay bar. +This event is fired when the user clicks on the app icon in the Dev Toolbar. -```ts title="src/my-plugin.js" {3-6} +```ts title="src/my-app.js" {3-6} export default { // ... init(canvas, eventTarget) { - eventTarget.addEventListener('plugin-toggled', (event) => { + eventTarget.addEventListener('app-toggled', (event) => { if (event.detail.state === true) { - console.log("The plugin is now enabled!") + console.log("The app is now enabled!") } }) } @@ -151,13 +151,13 @@ This event is fired when the user clicks on the plugin icon in the dev overlay b #### `state: boolean` -Indicates whether or not the plugin is enabled after the user's click. +Indicates whether or not the app is enabled after the user's click. ### `toggle-notification` -This event can be sent to inform the user that the plugin requires attention. +This event can be sent to inform the user that the app requires attention. -```ts title="src/my-plugin.js" {3-6} +```ts title="src/my-app.js" {3-6} export default { // ... init(canvas, eventTarget) { @@ -174,18 +174,18 @@ This event can be sent to inform the user that the plugin requires attention. #### `state: boolean` -Indicates whether or not the plugin has a notification for the user. When `true`, the plugin icon will be highlighted using a red dot. Conversely, when `false`, the highlight will be removed. If this property is not specified, `true` will be assumed. +Indicates whether or not the app has a notification for the user. When `true`, the app icon will be highlighted using a red dot. Conversely, when `false`, the highlight will be removed. If this property is not specified, `true` will be assumed. -### `toggle-plugin` +### `toggle-app` -This event can be sent from your plugin to change the state of your plugin. This can be useful, for instance, to implement a "Close" button in your plugin's UI. +This event can be sent from your app to change the state of your app. This can be useful, for instance, to implement a "Close" button in your app's UI. -```ts title="src/my-plugin.js" {3-6} +```ts title="src/my-app.js" {3-6} export default { // ... init(canvas, eventTarget) { eventTarget.dispatchEvent( - new CustomEvent('toggle-plugin', { + new CustomEvent('toggle-app', { detail: { state: false, }, @@ -197,40 +197,40 @@ This event can be sent from your plugin to change the state of your plugin. This #### `state: boolean` -Indicates whether or not the plugin should be enabled. When `true`, the plugin will be enabled. Conversely, when `false`, the plugin will be disabled. If this property is not specified, `true` will be assumed. +Indicates whether or not the app should be enabled. When `true`, the app will be enabled. Conversely, when `false`, the app will be disabled. If this property is not specified, `true` will be assumed. ## Client-Server Communication -Using [Vite's methods for client-server communication](https://vitejs.dev/guide/api-plugin.html#client-server-communication), dev overlay plugins can communicate with the server. +Using [Vite's methods for client-server communication](https://vitejs.dev/guide/api-plugin.html#client-server-communication), Dev Toolbar Apps can communicate with the server. -In addition to being able to send and receive custom messages, the dev overlay also sends the following messages, where `PLUGIN_ID` is the [plugin's ID](#id-string): +In addition to being able to send and receive custom messages, the Dev Toolbar also sends the following messages, where `APP_ID` is the [app's ID](#id-string): -### `astro-dev-overlay:PLUGIN_ID:initialized` +### `astro-dev-toolbar:APP_ID:initialized` -This message is sent when the plugin is initialized. The data for this message is empty. +This message is sent when the app is initialized. The data for this message is empty. ```ts title="integration.ts" { // ... "astro:server:setup": ({ server }) => { - server.ws.on("astro-dev-overlay:super-plugin:initialized", () => { - console.log("My plugin was initialized!"); + server.ws.on("astro-dev-toolbar:super-app:initialized", () => { + console.log("My app was initialized!"); }); }, // ... } ``` -### `astro-dev-overlay:PLUGIN_ID:toggled` +### `astro-dev-toolbar:APP_ID:toggled` -This message is sent when the user clicks on the plugin icon in the UI. The data for this message is a boolean indicating whether the plugin is enabled or not. +This message is sent when the user clicks on the app icon in the UI. The data for this message is a boolean indicating whether the app is enabled or not. ```ts title="integration.ts" { // ... "astro:server:setup": ({ server }) => { - server.ws.on("astro-dev-overlay:super-plugin:toggled", (data) => { - console.log(`My plugin is now ${data.state ? "enabled" : "disabled"}!`); + server.ws.on("astro-dev-toolbar:super-app:toggled", (data) => { + console.log(`My app is now ${data.state ? "enabled" : "disabled"}!`); }); }, // ... @@ -238,63 +238,63 @@ This message is sent when the user clicks on the plugin icon in the UI. The data ``` :::note -The built-in `connection` event from Vite fires **before** dev overlay plugins are initialized and therefore cannot be used directly by plugins. Instead, use the `astro-dev-overlay:PLUGIN_ID:initialized` event. +The built-in `connection` event from Vite fires **before** Dev Toolbar apps are initialized and therefore cannot be used directly by apps. Instead, use the `astro-dev-toolbar:APP_ID:initialized` event. ::: ## UI Toolkit -The dev overlay includes a set of web components that can be used to build plugins with a consistent look and feel. +The Dev Toolbar includes a set of web components that can be used to build apps with a consistent look and feel. -### `astro-dev-overlay-window` +### `astro-dev-toolbar-window` Shows a window with optionally a title and an icon. -`window-title` is a string that will be shown at the top of the overlay window. `window-icon` can either be a string of a SVG file or an icon from [the icon list](#icons). +`window-title` is a string that will be shown at the top of the toolbar window. `window-icon` can either be a string of a SVG file or an icon from [the icon list](#icons). The slot of the component will be used as the content of the window. ```html - +

My content

- + ``` -### `astro-dev-overlay-card` +### `astro-dev-toolbar-card` Shows a card with optionally an [`icon`](#icons). Optionally, if a `link` is passed, the card will be clickable and will open the link in a new tab. The slot of the component will be used as the content of the card. ```html -Report an issue +Report an issue ``` -### `astro-dev-overlay-toggle` +### `astro-dev-toolbar-toggle` Shows a toggle element, acting as a checkbox. This element internally is a simple wrapper around a native `` element. The checkbox element can be accessed using the `input` property. ```ts -const toggle = document.createElement('astro-dev-overlay-toggle'); +const toggle = document.createElement('astro-dev-toolbar-toggle'); toggle.input.addEventListener('change', (evt) => { console.log(`The toggle is now ${evt.currentTarget.checked ? 'enabled' : 'disabled'}!`); }); ``` -### `astro-dev-overlay-highlight` +### `astro-dev-toolbar-highlight` Can be used to highlight an element on the page. In most cases, you'll want to position and resize this element using the `top`, `left`, `width` and `height` CSS properties to match the element you want to highlight. An [icon](#icons) can also be specified using the `icon` attribute and will be shown in the top right corner of the highlight. ```html - + ``` ```ts const elementToHighlight = document.querySelector('h1'); const rect = elementToHighlight.getBoundingClientRect(); -const highlight = document.createElement('astro-dev-overlay-highlight'); +const highlight = document.createElement('astro-dev-toolbar-highlight'); highlight.style.top = `${Math.max(rect.top + window.scrollY - 10, 0)}px`; highlight.style.left = `${Math.max(rect.left + window.scrollX - 10, 0)}px`; @@ -303,7 +303,7 @@ highlight.style.height = `${rect.height + 15}px`; highlight.icon = 'astro:logo'; ``` -### `astro-dev-overlay-tooltip` +### `astro-dev-toolbar-tooltip` Shows a tooltip with different sections. This component is set to `display: none;` by default and can be made visible using a `data-show="true"` attribute. @@ -321,7 +321,7 @@ Sections are defined using the `sections` property. This property is an array of ``` ```ts -const tooltip = document.createElement('astro-dev-overlay-tooltip'); +const tooltip = document.createElement('astro-dev-toolbar-tooltip'); tooltip.sections = [{ title: 'My section', @@ -334,14 +334,14 @@ tooltip.sections = [{ }] ``` -This component is often combined with the `astro-dev-overlay-highlight` component to show a tooltip when hovering a highlighted element: +This component is often combined with the `astro-dev-toolbar-highlight` component to show a tooltip when hovering a highlighted element: ```ts -const highlight = document.createElement('astro-dev-overlay-highlight'); +const highlight = document.createElement('astro-dev-toolbar-highlight'); // Position the highlight... -const tooltip = document.createElement('astro-dev-overlay-tooltip'); +const tooltip = document.createElement('astro-dev-toolbar-tooltip'); // Add sections to the tooltip... @@ -369,5 +369,5 @@ Currently, the following icons are available and can be used in any component th In addition to these included icons, you can also pass a string containing the SVG markup of the icon you want to use. ```html -Read more in the Astro Docs! +Read more in the Astro Docs! ``` diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 3a534bf6a372e..61741d3dc45ef 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -150,9 +150,9 @@ export default [ key: 'reference/image-service-reference', }, { - text: 'Dev Overlay Plugin API', - slug: 'reference/dev-overlay-plugin-reference', - key: 'reference/dev-overlay-plugin-reference', + text: 'Dev Toolbar App API', + slug: 'reference/dev-toolbar-app-reference', + key: 'reference/dev-toolbar-app-reference', }, { text: 'Template Directives', diff --git a/vercel.json b/vercel.json index 249f60448726f..0969194bc479c 100644 --- a/vercel.json +++ b/vercel.json @@ -14,7 +14,10 @@ "source": "/en/reference/renderer-reference/", "destination": "/en/reference/integrations-reference/" }, - + { + "source": "/en/reference/dev-overlay-plugin-reference/", + "destination": "/en/reference/dev-toolbar-app-reference/" + }, { "source": "/en/core-concepts/component-hydration/", "destination": "/en/concepts/islands/" }, { "source": "/core-concepts/component-hydration/", "destination": "/en/concepts/islands/" }, From 4393e25dff92d3a97abb022b006dc646732badf2 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Sat, 2 Dec 2023 14:30:26 -0400 Subject: [PATCH 02/11] adds content from line 357 to end of file from other PR --- .../reference/dev-toolbar-app-reference.mdx | 27 ++++++++++++++----- 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx index c492cbdea0a44..8f4b9a5c8f64e 100644 --- a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx +++ b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx @@ -354,7 +354,21 @@ highlight.addEventListener('mouseout', () => { }); ``` -### Icons +### `astro-dev-toolbar-icon` + +Shows an icon. An icon from [the icon list](#icons) can be specified using the `icon` attribute, or the SVG markup of an icon can be passed as a slot. + +```html + +``` + +```html + + ... + +``` + +#### Icons Currently, the following icons are available and can be used in any component that accepts an icon: @@ -365,9 +379,10 @@ Currently, the following icons are available and can be used in any component th - `file-search` - `check-circle` - `gear` +- `lightbulb` +- `file-search` +- `checkmark` +- `dots-three` +- `copy` -In addition to these included icons, you can also pass a string containing the SVG markup of the icon you want to use. - -```html -Read more in the Astro Docs! -``` +All of the above icons have `fill="currentColor"` set by default and will inherit their color from the parent element. From 3eb4db823b8f84898687c083a5a831d89798c11a Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 4 Dec 2023 08:01:51 -0400 Subject: [PATCH 03/11] bringing in updated comment from PR 5516 --- .../reference/dev-toolbar-app-reference.mdx | 68 +++++++++++++++++-- vercel.json | 4 +- 2 files changed, 66 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx index 8f4b9a5c8f64e..2e03178d98ae8 100644 --- a/src/content/docs/en/reference/dev-toolbar-app-reference.mdx +++ b/src/content/docs/en/reference/dev-toolbar-app-reference.mdx @@ -247,21 +247,81 @@ The Dev Toolbar includes a set of web components that can be used to build apps ### `astro-dev-toolbar-window` -Shows a window with optionally a title and an icon. +Shows a window. -`window-title` is a string that will be shown at the top of the toolbar window. `window-icon` can either be a string of a SVG file or an icon from [the icon list](#icons). The slot of the component will be used as the content of the window. ```html - +

My content

 ``` +When building a window using JavaScript, slotted content must go inside the light DOM of the component. + +```js +const myWindow = document.createElement('astro-dev-toolbar-window'); +const myContent = document.createElement('p'); +myContent.textContent = 'My content'; + +// use appendChild directly on the window +myWindow.appendChild(myContent); +``` + +### `astro-dev-toolbar-button` + +Shows a button. + +The slot of the component will be used as the content of the button. + +```js +const myButton = document.createElement('astro-dev-toolbar-button'); +myButton.textContent = 'Click me!'; +myButton.buttonStyle = "purple"; +myButton.size = "medium"; + +myButton.addEventListener('click', () => { + console.log('Clicked!'); +}); +``` + +#### `size` + +The size of the button (small, medium, large). + +#### `button-style` + +The style of the button (`ghost`, `outline`, `purple`, `gray`, `red`). When using `ghost`, the button itself is invisible and only the content of the button will be shown. + +In JavaScript, set this property using the `buttonStyle` property to avoid conflict with the native `style` property. + +### `astro-dev-toolbar-badge` + +Shows a badge. + +The slot of the component will be used as the content of the badge. + +```html +My badge +``` + +#### `size` + +The size of the badge (`small`, `large`). + +#### `badge-style` + +The style (color) of the badge (`purple`, `gray`, `red`, `green`, `yellow`). + +In JavaScript, set this property using the `buttonStyle` property to avoid conflict with the native `style` property. + ### `astro-dev-toolbar-card` -Shows a card with optionally an [`icon`](#icons). Optionally, if a `link` is passed, the card will be clickable and will open the link in a new tab. +Shows a card. Specify an optional `link` attribute to make the card act like an `` element. + + +When making a card using using JavaScript, a `clickAction` property can be specified to make the card act like a `