diff options
Diffstat (limited to 'browser/components/migration/docs')
5 files changed, 338 insertions, 0 deletions
diff --git a/browser/components/migration/docs/index.rst b/browser/components/migration/docs/index.rst new file mode 100644 index 0000000000..be22b951cb --- /dev/null +++ b/browser/components/migration/docs/index.rst @@ -0,0 +1,16 @@ +.. _components/migration: + +========= +Migration +========= + +The migration component is responsible for bringing data from outside applications running on the same computer into Firefox. This is typically done via a wizard where users can choose what types of data to migrate over. + +The migrator is also used during a "Profile Refresh" to pave over a newly created Firefox profile with some data from an older one. + +.. toctree:: + :maxdepth: 3 + + migration-utils + migrators + migration-wizard diff --git a/browser/components/migration/docs/migration-utils.rst b/browser/components/migration/docs/migration-utils.rst new file mode 100644 index 0000000000..c1ecb41d8b --- /dev/null +++ b/browser/components/migration/docs/migration-utils.rst @@ -0,0 +1,5 @@ +======================== +MigrationUtils Reference +======================== +.. js:autoclass:: MigrationUtils + :members: diff --git a/browser/components/migration/docs/migration-wizard-architecture-diagram.svg b/browser/components/migration/docs/migration-wizard-architecture-diagram.svg new file mode 100644 index 0000000000..4c5fbf5bc5 --- /dev/null +++ b/browser/components/migration/docs/migration-wizard-architecture-diagram.svg @@ -0,0 +1,128 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" viewBox="-0.5 -0.5 711 541"> + <path d="M707.27 385.71V540H440V360h229.09Z" fill="#FFF" stroke="#8a8a8a" stroke-miterlimit="10" pointer-events="all"/> + <path d="M669.09 360c3.11 6.02-2 12.22-13.64 16.53L710 387Z" fill="#FFF" stroke="#8a8a8a" stroke-miterlimit="10" pointer-events="all"/> + <path fill="none" pointer-events="all" d="M440 500h120v30H440z"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:118px;height:1px;padding-top:515px;margin-left:441px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0);"> + <div style="display:inline-block;font-size:12px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;white-space:normal;overflow-wrap:normal"> + (X)HTML Document + </div> + </div> + </div> + </foreignObject> + <text x="500" y="519" font-family="Helvetica" font-size="12" text-anchor="middle">(X)HTML Document</text> + </switch> + <path fill="#FFF" stroke="#000" pointer-events="all" d="M480 400h180v100H480z"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:178px;height:1px;padding-top:450px;margin-left:481px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0);"> + <div style="display:inline-block;font-size:12px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;white-space:normal;overflow-wrap:normal"> + <migration-wizard> + </div> + </div> + </div> + </foreignObject> + <text x="570" y="454" font-family="Helvetica" font-size="12" text-anchor="middle"><migration-wizard></text> + </switch> + <path fill="#FFF" stroke="#8a8a8a" pointer-events="all" d="M420 160h210v100H420z"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:208px;height:1px;padding-top:210px;margin-left:421px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0);"> + <div style="display:inline-block;font-size:12px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;white-space:normal;overflow-wrap:normal"> + MigrationWizardChild + </div> + </div> + </div> + </foreignObject> + <text x="525" y="214" font-family="Helvetica" font-size="12" text-anchor="middle">MigrationWizardChild</text> + </switch> + <path d="M216.37 210h197.26" fill="none" stroke="#000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/> + <path d="m211.12 210 7-3.5-1.75 3.5 1.75 3.5ZM418.88 210l-7 3.5 1.75-3.5-1.75-3.5Z" stroke="#000" stroke-miterlimit="10" pointer-events="all"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:1px;height:1px;padding-top:208px;margin-left:314px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);"> + <div style="display:inline-block;font-size:11px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;background-color:#fff;white-space:nowrap"> + JSWindowActor messages + </div> + </div> + </div> + </foreignObject> + <text x="314" y="211" font-family="Helvetica" font-size="11" text-anchor="middle">JSWindowActor messages</text> + </switch> + <path d="M105 153.63v-47.26" fill="none" stroke="#000" stroke-miterlimit="10" pointer-events="stroke"/> + <path d="m105 158.88-3.5-7 3.5 1.75 3.5-1.75ZM105 101.12l3.5 7-3.5-1.75-3.5 1.75Z" stroke="#000" stroke-miterlimit="10" pointer-events="all"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:1px;height:1px;padding-top:130px;margin-left:105px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);"> + <div style="display:inline-block;font-size:11px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;background-color:#fff;white-space:nowrap"> + Direct function calls + </div> + </div> + </div> + </foreignObject> + <text x="105" y="133" font-family="Helvetica" font-size="11" text-anchor="middle">Direct function calls</text> + </switch> + <path fill="#FFF" stroke="#8a8a8a" pointer-events="all" d="M0 160h210v100H0z"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:208px;height:1px;padding-top:210px;margin-left:1px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0);"> + <div style="display:inline-block;font-size:12px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;white-space:normal;overflow-wrap:normal"> + MigrationWizardParent + </div> + </div> + </div> + </foreignObject> + <text x="105" y="214" font-family="Helvetica" font-size="12" text-anchor="middle">MigrationWizardParent</text> + </switch> + <path fill="#FFF" stroke="#8a8a8a" pointer-events="all" d="M0 0h210v100H0z"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:208px;height:1px;padding-top:50px;margin-left:1px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0);"> + <div style="display:inline-block;font-size:12px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;white-space:normal;overflow-wrap:normal"> + MigrationUtils + </div> + </div> + </div> + </foreignObject> + <text x="105" y="54" font-family="Helvetica" font-size="12" text-anchor="middle">MigrationUtils</text> + </switch> + <path d="M525 400V266.37" fill="none" stroke="#000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/> + <path d="m525 261.12 3.5 7-3.5-1.75-3.5 1.75Z" stroke="#000" stroke-miterlimit="10" pointer-events="all"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:1px;height:1px;padding-top:340px;margin-left:527px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);"> + <div style="display:inline-block;font-size:11px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;background-color:#fff;white-space:nowrap"> + DOM Events + </div> + </div> + </div> + </foreignObject> + <text x="527" y="343" font-family="Helvetica" font-size="11" text-anchor="middle">DOM Events</text> + </switch> + <path d="M572.22 393.64 577.5 260" fill="none" stroke="#000" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/> + <path d="m572.02 398.88-3.22-7.13 3.42 1.89 3.57-1.61Z" stroke="#000" stroke-miterlimit="10" pointer-events="all"/> + <switch transform="translate(-.5 -.5)"> + <foreignObject style="overflow:visible;text-align:left" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"> + <div xmlns="http://www.w3.org/1999/xhtml" style="display:flex;align-items:unsafe center;justify-content:unsafe center;width:1px;height:1px;padding-top:311px;margin-left:581px"> + <div style="box-sizing:border-box;font-size:0;text-align:center" data-drawio-colors="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);"> + <div style="display:inline-block;font-size:11px;font-family:Helvetica;color:#000;line-height:1.2;pointer-events:all;background-color:#fff;white-space:nowrap"> + Direct function calls + </div> + </div> + </div> + </foreignObject> + <text x="581" y="314" font-family="Helvetica" font-size="11" text-anchor="middle">Direct function calls</text> + </switch> +</svg> diff --git a/browser/components/migration/docs/migration-wizard.rst b/browser/components/migration/docs/migration-wizard.rst new file mode 100644 index 0000000000..dd5905443c --- /dev/null +++ b/browser/components/migration/docs/migration-wizard.rst @@ -0,0 +1,77 @@ +========================== +Migration Wizard Reference +========================== + +The migration wizard is the piece of UI that allows users to migrate from other browsers to Firefox. + + .. note:: + Firefox has had a legacy migration wizard for many years, and this has historically been a top-level XUL dialog window. **This documentation is not for the legacy migration wizard**, but is instead for an in-progress replacement migration wizard. + + The new migration wizard can be enabled by setting ``browser.migrate.content-modal.enabled`` to ``true``. + +The migration wizard can be embedded in the following contexts: + +1. In a top level stand-alone dialog window +2. Within privileged ``about:`` pages, like ``about:welcome``, and ``about:preferences`` + +To accommodate these contexts, the migration wizard was developed as a reusable component using pure HTML, with an architecture that decouples the control of the wizard from how the wizard is presented to the user. This architecture not only helps to ensure that the wizard can function similarly in these different contexts, but also makes the component viewable in tools like Storybook for easier development. + + +High-level Overview +------------------- + +The following diagram tries to illustrate how the pieces of the migration wizard fit together: + +.. image:: migration-wizard-architecture-diagram.svg + +``MigrationWizard`` reusable component +====================================== + +The ``MigrationWizard`` reusable component (``<migration-wizard>``) is a custom element that can be imported from ``migration-wizard.mjs``. The module is expected to load in a DOM window context, whereupon the custom element is automatically registered for that document. + +After binding to the document, if the ``MigrationWizard`` has the ``auto-request-state`` attribute set on it, it will dispatch a ``MigrationWizard:RequestState`` custom event, which causes a ``MigrationWizardChild`` to instantiate and be associated with it. After receiving the migrator state from the ``MigrationWizardParent``, the ``MigrationWizardChild`` will dispatch a ``MigrationWizard:Ready`` event on the ``MigrationWizard``, mainly to aid in testing. The ``auto-request-state`` attribute is useful in situations where the ``MigrationWizard`` element is being used declaratively. + +If the ``auto-request-state`` attribute is not set, calling ``requestState()`` on the ``MigrationWizard`` will perform the above step. This is useful in situations where the ``MigrationWizard`` element is being constructed dynamically and the callers wants finer-grain control over when the state will be requested. + +Notably, the ``MigrationWizard`` does not contain any internal logic or privileged code to perform any migrations or to directly interact with the migration mechanisms. Its sole function is to accept input from the user and emit that input as events. The associated ``MigrationWizardChild`` will listen for those events, and take care of calling into the ``MigrationWizard`` to update the state of the reusable component. This means that the reusable component can be embedded in unprivileged contexts and have its states presented in a tool like Storybook. + +If the ``MigrationWizard`` is embedded in a dialog, it should have the ``dialog-mode`` attribute set on it so that dialog-appropriate buttons and styles are applied. + +``MigrationWizardConstants`` +============================ + +The ``MigrationWizardConstants`` module exports a single object of the same name. The properties of that object are constants that can be used to set the state of a ``MigrationWizard`` instance using ``MigrationWizard.setState``. + +``MigrationWizardChild`` +========================= + +The ``MigrationWizardChild`` is a ``JSWindowActorChild`` (see `JSActors`_) that is responsible for listening for events from a ``MigrationWizard``, and then either updating the state of that ``MigrationWizard`` immediately, or to message its paired ``MigrationWizardParent`` to perform tasks with ``MigrationUtils``. + + .. note:: + While a ``MigrationWizardChild`` can run in a content process (for out-of-process pages like ``about:welcome``), it can also run in parent-process contexts - for example, within the parent-process ``about:preferences`` page, or standalone window dialog. The same flow of events and messaging applies in all contexts. + +The ``MigrationWizardChild`` also waives Xrays so that it can directly call the ``setState`` method to update the appearance of the ``MigrationWizard``. See `XrayVision`_ for much more information on Xrays. + +.. js:autoclass:: MigrationWizardChild + :members: + +``MigrationWizardParent`` +========================= + +The ``MigrationWizardParent`` is a ``JSWindowActorParent`` (see `JSActors`_) that is responsible for listening for messages from the paired ``MigrationWizardChild`` to perform operations with ``MigrationUtils``. Effectively, all of the heavy lifting of actually performing the migrations will be kicked off by the ``MigrationWizardParent`` by calling into ``MigrationUtils``. State updates for things like migration progress will be sent back down to the ``MigrationWizardChild`` to then be reflected in the appearance of the ``MigrationWizard``. + +Since the ``MigrationWizard`` might be embedded in unprivileged documents, additional checks are placed in the message handler for ``MigrationWizardParent`` to ensure that the document is either running in the parent process or the privileged about content process. The `JSActors`_ registration for ``MigrationWizardParent`` and ``MigrationWizardChild`` also ensures that the actors only load for built-in documents. + +.. js:autoclass:: MigrationWizardParent + :members: + +``migration-dialog-window.html`` +================================ + +This document is meant for being loaded in a window dialog, and embeds the ``MigrationWizard`` reusable component, setting ``dialog-mode`` on it. It listens for dialog-specific events from the ``MigrationWizard``, such as ``MigrationWizard:Close``, which indicates that a "Cancel" button that should close the dialog was clicked. + +Pages like ``about:preferences`` or ``about:welcome`` can embed the ``MigrationWizard`` component directly, rather than use ``migration-dialog-window.html``. + + +.. _JSActors: /dom/ipc/jsactors.html +.. _XrayVision: /dom/scriptSecurity/xray_vision.html diff --git a/browser/components/migration/docs/migrators.rst b/browser/components/migration/docs/migrators.rst new file mode 100644 index 0000000000..a8694343d5 --- /dev/null +++ b/browser/components/migration/docs/migrators.rst @@ -0,0 +1,112 @@ +=================== +Migrators Reference +=================== + +There are currently two types of migrators: browser migrators, and file migrators. Browser migrators will migrate various resources from another browser. A file migrator allows the user to migrate data through an intermediary file (like passwords from a .CSV file). + +Browser migrators +================= + +MigratorBase class +------------------ +.. js:autoclass:: MigratorBase + :members: + +Chrome and Chrome variant migrators +----------------------------------- + +The ``ChromeProfileMigrator`` is subclassed ino order to provide migration capabilities for variants of the Chrome browser. + +ChromeProfileMigrator class +=========================== +.. js:autoclass:: ChromeProfileMigrator + :members: + +BraveProfileMigrator class +========================== +.. js:autoclass:: BraveProfileMigrator + :members: + +CanaryProfileMigrator class +=========================== +.. js:autoclass:: CanaryProfileMigrator + :members: + +ChromeBetaMigrator class +======================== +.. js:autoclass:: ChromeBetaMigrator + :members: + +ChromeDevMigrator class +======================= +.. js:autoclass:: ChromeDevMigrator + :members: + +Chromium360seMigrator class +=========================== +.. js:autoclass:: Chromium360seMigrator + :members: + +ChromiumEdgeMigrator class +========================== +.. js:autoclass:: ChromiumEdgeMigrator + :members: + +ChromiumEdgeBetaMigrator class +============================== +.. js:autoclass:: ChromiumEdgeBetaMigrator + :members: + +ChromiumProfileMigrator class +============================= +.. js:autoclass:: ChromiumProfileMigrator + :members: + +OperaProfileMigrator class +========================== +.. js:autoclass:: OperaProfileMigrator + :members: + +OperaGXProfileMigrator class +============================ +.. js:autoclass:: OperaGXProfileMigrator + :members: + +VivaldiProfileMigrator class +============================ +.. js:autoclass:: VivaldiProfileMigrator + :members: + +EdgeProfileMigrator class +------------------------- +.. js:autoclass:: EdgeProfileMigrator + :members: + +FirefoxProfileMigrator class +---------------------------- +.. js:autoclass:: FirefoxProfileMigrator + :members: + +IEProfileMigrator class +----------------------- +.. js:autoclass:: IEProfileMigrator + :members: + +File migrators +============== + +.. js:autofunction:: FilePickerConfigurationFilter + :short-name: + +.. js:autofunction:: FilePickerConfiguration + :short-name: + +FileMigratorBase class +---------------------- +.. js:autoclass:: FileMigratorBase + :members: + +PasswordFileMigrator class +-------------------------- +.. js:autoclass:: PasswordFileMigrator + :members: |
