Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Inline Menu Deep Dive Documentation #467

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Update Inline Menu Deep Dive Documentation #467

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c9daa8
Update Inline Menu Deep Dive Documentation
cagonzalezcs Oct 18, 2024
8d37a43
Merge branch 'main' into autofill/update-inline-menu-documentation
cagonzalezcs Nov 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions docs/architecture/deep-dives/autofill/autofill-menu.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,17 @@ The core scripts for the Autofill Menu feature are located within the
directory of the [`clients` repository](https://github.com/bitwarden/clients). These files form the
backbone of the feature's functionality.

| File | Responsibility |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`overlay.background.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/background/overlay.background.ts) | Orchestrates communication among three key components: the content script containing the [`AutofillOverlayContentService`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/services/autofill-overlay-content.service.ts), the extension pages displaying the Autofill Menu UI, and the extension background script. It facilitates the activation of various logic sequences by transmitting messages between these components. |
| [`autofill-overlay-content.service.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/services/autofill-overlay-content.service.ts) | Contains the initialization logic for the content script of the Autofill Menu. It is initialized within the content script encompassing the [`AutofillInit`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/content/autofill-init.ts) class. The behavior for the Autofill Menu is setup on each form field of a webpage when the first `collectPageDetails` message is received within the webpage. This service is responsible for creating the custom elements that constitute the Autofill Menu UI and managing the behavior associated with user interactions on the webpage’s form fields. |
| [`autofill-overlay-iframe-element.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/iframe-content/autofill-overlay-iframe-element.ts) | Serves as a parent class for initializing the Autofill Menu button and list custom elements. It constructs a closed shadow DOM and initializes the [`AutofillOverlayIframeService`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/iframe-content/autofill-overlay-iframe.service.ts). This service is responsible for injecting an iframe, which either displays the Autofill Menu list or button page. |
| [`autofill-overlay-button-iframe.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/iframe-content/autofill-overlay-button-iframe.ts) | Initializes the custom Autofill Menu button element that is injected into the DOM. This script extends the [`AutofillOverlayIframeElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/iframe-content/autofill-overlay-iframe-element.ts) class and initializes properties specific to the Autofill Menu button page. |
| [`autofill-overlay-list-iframe.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/iframe-content/autofill-overlay-list-iframe.ts) | Initializes the custom Autofill Menu list element that is injected into the DOM. This script extends the [`AutofillOverlayIframeElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/iframe-content/autofill-overlay-iframe-element.ts) class, and initializes properties unique to the Autofill Menu list page. |
| [`autofill-overlay-iframe.service.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/iframe-content/autofill-overlay-iframe.service.ts) | Handles the functionality of the Autofill Menu page iframes, which are contained within the custom web component injected into a user's page. This script acts as an intermediary for message passing between the extension background and the iframe within the custom web component. |
| [`autofill-overlay-page-element.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/pages/shared/autofill-overlay-page-element.ts) | Serves as the parent class for individual Autofill Menu page scripts. It encapsulates common logic used across Autofill Menu pages, including initialization routines, establishing global listeners, handling window message posting to the parent of the iframe, and managing focus redirection from the iframe element. |
| [`autofill-overlay-button.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/pages/button/autofill-overlay-button.ts) | Utilized within [`button.html`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/pages/button/button.html) to facilitate the Autofill Menu button extension page within a sandboxed iframe. It inherits from the [`AutofillOverlayPageElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/pages/shared/autofill-overlay-page-element.ts) class and is specifically tasked with managing the behavior of the Autofill Menu button injected into webpages. |
| [`autofill-overlay-list.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/pages/list/autofill-overlay-list.ts) | Utilized within [`list.html`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/pages/list/list.html) to facilitate the Autofill Menu list extension page within a sandboxed iframe. It inherits from the [`AutofillOverlayPageElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/pages/shared/autofill-overlay-page-element.ts) class and is specifically tasked with managing the behavior of the Autofill Menu list injected into webpages. |
| File | Responsibility |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`overlay.background.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/background/overlay.background.ts) | Orchestrates communication among three key components: the content script containing the [`AutofillOverlayContentService`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/services/autofill-overlay-content.service.ts), the extension pages displaying the Autofill Menu UI, and the extension background script. It facilitates the activation of various logic sequences by transmitting messages between these components. |
| [`autofill-overlay-content.service.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/services/autofill-overlay-content.service.ts) | Contains the initialization logic for the content script of the Autofill Menu. It is initialized within the content script encompassing the [`AutofillInit`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/content/autofill-init.ts) class. The behavior for the Autofill Menu is setup on each form field of a webpage when the first `collectPageDetails` message is received within the webpage. This service is responsible for creating the custom elements that constitute the Autofill Menu UI and managing the behavior associated with user interactions on the webpage’s form fields. |
| [`autofill-inline-menu-iframe-element.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/iframe-content/autofill-inline-menu-iframe-element.ts) | Serves as a parent class for initializing the Autofill Menu button and list custom elements. It constructs a closed shadow DOM and initializes the [`AutofillInlineMenuIframeService`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/iframe-content/autofill-inline-menu-iframe.service.ts). This service is responsible for injecting an iframe, which either displays the Autofill Menu list or button page. |
| [`autofill-inline-menu-button-iframe.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/iframe-content/autofill-inline-menu-button-iframe.ts) | Initializes the custom Autofill Menu button element that is injected into the DOM. This script extends the [`AutofillInlineMenuIframeElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/iframe-content/autofill-inline-menu-iframe-element.ts) class and initializes properties specific to the Autofill Menu button page. |
| [`autofill-inline-menu-list-iframe.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/iframe-content/autofill-inline-menu-list-iframe.ts) | Initializes the custom Autofill Menu list element that is injected into the DOM. This script extends the [`AutofillInlineMenuIframeElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/iframe-content/autofill-inline-menu-iframe-element.ts) class, and initializes properties unique to the Autofill Menu list page. |
| [`autofill-inline-menu-iframe.service.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/iframe-content/autofill-inline-menu-iframe.service.ts) | Handles the functionality of the Autofill Menu page iframes, which are contained within the custom web component injected into a user's page. This script acts as an intermediary for message passing between the extension background and the iframe within the custom web component. |
| [`autofill-inline-menu-page-element.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/pages/shared/autofill-inline-menu-page-element.ts) | Serves as the parent class for individual Autofill Menu page scripts. It encapsulates common logic used across Autofill Menu pages, including initialization routines, establishing global listeners, handling window message posting to the parent of the iframe, and managing focus redirection from the iframe element. |
| [`autofill-inline-menu-button.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/pages/button/autofill-inline-menu-button.ts) | Utilized within [`button.html`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/pages/button/button.html) to facilitate the Autofill Menu button extension page within a sandboxed iframe. It inherits from the [`AutofillInlineMenuPageElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/pages/shared/autofill-inline-menu-page-element.ts) class and is specifically tasked with managing the behavior of the Autofill Menu button injected into webpages. |
| [`autofill-inline-menu-list.ts`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/pages/list/autofill-inline-menu-list.ts) | Utilized within [`list.html`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/pages/list/list.html) to facilitate the Autofill Menu list extension page within a sandboxed iframe. It inherits from the [`AutofillInlineMenuPageElement`](https://github.com/bitwarden/clients/blob/main/apps/browser/src/autofill/overlay/inline-menu/pages/shared/autofill-inline-menu-page-element.ts) class and is specifically tasked with managing the behavior of the Autofill Menu list injected into webpages. |

## Implementation Details

Expand Down Expand Up @@ -85,9 +85,9 @@ directly access these elements or their content.
The user interface representing the Autofill Menu consists of extension pages rendered within
sandboxed iframes. These sandboxed iframes are structured within the custom elements injected into a
user's webpage and represent the Autofill Menu
[button](https://github.com/bitwarden/clients/tree/main/apps/browser/src/autofill/overlay/pages/button)
[button](https://github.com/bitwarden/clients/tree/main/apps/browser/src/autofill/overlay/inline-menu/pages/button)
and
[list](https://github.com/bitwarden/clients/tree/main/apps/browser/src/autofill/overlay/pages/list)
[list](https://github.com/bitwarden/clients/tree/main/apps/browser/src/autofill/overlay/inline-menu/pages/list)
UI elements.

Rendering these views within a sandboxed iframe sets clear limitations on how these pages can
Expand Down