Extension:GrowthExperiments/Technical documentation/Frontend

From mediawiki.org

Client modules map[edit]

ResourceLoader Module Usage Server side rendering Base UI components Custom UI components Notes
ext.growthExperiments.Account Set up ULS for WelcomeSurvey; show confirm email in Special:CreateAccount MessageBox

TagMultiselectWidget

ext.growthExperiments.Account.styles Style elements in ext.growthExperiments.Account, custom landing pages, Special:Contributions
ext.growthExperiments.DataStore Manage states for filters and newcomer tasks
ext.growthExperiments.Help Ask help dialog; contents of the help panel Layouts (PanelLayout, IndexLayout, StackLayout)

ProcessDialog SearchInputWidget

ext.growthExperiments.HelpPanel Help panel CTA, help panel popup; suggested edits guidance HelpPanelButton

SuggestedEditsPeek

ext.growthExperiments.Homepage.ConfirmEmailNotice Show a notification after the user confirms their email
ext.growthExperiments.Homepage.Impact Homepage module; Show page views for edited articles (activated) or open suggested edits (unactivated) PopupButtonWidget
ext.growthExperiments.Homepage.Logger Logger class for homepagemodule schema
ext.growthExperiments.Homepage.Logging Set up logging for homepage modules
ext.growthExperiments.Homepage.Mentorship Homepage module; Show questions posted to mentor; opt in/out of mentorship ButtonMenuSelectWidget

MessageDialog

ext.growthExperiments.Homepage.mobile Set up mobile overlays for homepage modules MobileOverlay (MobileFrontend)

Drawer (MobileFrontend)

Maybe it's worth considering splitting out the overlays from the server-side rendered view
ext.growthExperiments.Homepage.styles Style server-side rendered elements of the homepage
ext.growthExperiments.Homepage.SuggestedEdits Homepage module; suggested edits feed and filters ProcessDialog

PanelLayout PopupButtonWidget MessageWidget SwipePane

SuggestedEditsPeek
ext.growthExperiments.HomepageDiscovery Show banner w/instructions on how to back to Special:Homepage; Remove mobile discovery banner after it's been closed
ext.growthExperiments.MentorDashboard Allow mentors to manage their mentees, their mentorship status mw.widgets.UserInputWidget

ProcessDialog

There's room for improvement in the UI in terms of mobile/responsive layouts and loading/progress feedback to users
ext.growthExperiments.MentorDashboard/MenteeOverview Browse mentees, see mentee stats Inputs (NumberInput, ButtonSelect, CheckboxInput) FilterDropdown
ext.growthExperiments.MentorDashboard/MentorTools Claim mentees, set mentor availability Select (Browser native), Dialog
ext.growthExperiments.MentorDashboard/Resources Lists useful links for mentors Could be a candidate for experimentings with custom SSR on PHP. That means building a mustache template in the server that matches the generated HTML of a Vue component.
ext.growthExperiments.PostEdit Show dialog upon task completion MessageWidget CollapsibleDrawer
ext.growthExperiments.StructuredTask Base classes for structured tasks VE classes
ext.growthExperiments.StructuredTask.desktop Desktop-specific classes for structured tasks VE classes
ext.growthExperiments.StructuredTask.mobile Mobile-specific classes for structured tasks VE classes
ext.growthExperiments.StructuredTask.PreEdit Check for structured task eligiblity; show onboarding dialog (mobile) ProcessDialog MultiPaneDialog

SwipePane

Might be a good candidate if we have the dialog component but since the onboarding is bundled w/StructuredTask module, we may need to research bundling Vue-based modules with VE
ext.growthExperiments.SuggestedEditSession Manage states for suggested edits

Disclaimer: the table is not updated since May 2022

Unit testing[edit]

The GrowthExperiments extension client code can and should be tested with one of MediaWiki's preferred runners: jest or qunit. Specifically Jest is used for running Vue components unit tests and QUnit for running other Javascript scripts. QUnit tests live under the folder tests/qunit whereas Jest tests are normally placed in source directories by the side of the script they are testing. The current CI setup (tbd: add reference to doc/sources) will execute both kinds of tests whenever a change is pushed to gerrit. Sadly there's not a single command (yet) to run them all from a developer environment.

QUnit[edit]

For running QUnit tests use ./node_modules/.bin/grunt qunit --qunit-component=GrowthExperiments from the root mediawiki directory.

Jest[edit]

For running Jest tests use the NPM script npm run test:jest from the GrowthExperiments extension directory.

Snapshot testing[edit]

Jest supports snapshot testing which is a useful feature to make sure UIs do not change unexpectedly. To create a snapshot file from a component for the first time use npm run test:jest. To update an existing snapshot based on source component changes use npm run test:jest:update

Testing a Codex patch in the frontend documentation[edit]

Pull the relevant Codex patch

/projects/codex$ git review -d 1234

Build all Codex packages since the build of packages/codex may depend on the build of packages/codex-design-tokens

/projects/codex$ npm run build-all

Link the local package into your package

$ cd /projects/codex/packages/codex             # go to the codex package directory
/projects/codex/packages/codex$ npm link        # create a global link
$ cd /projects/my-node-package                  # go to your package directory
/projects/my-node-$ npm link @wikimedia/codex   # link-install the codex package

All import '@wikimedia/codex' or require( '@wikimedia/codex' ) statements should work as expected. Relative imports in .{vue,js,ts} files should also continue to work, eg: import '../../node_modules/@wikimedia/codex/dist/codex.style.css';

VitePress projects[edit]

On VitePress projects only files within the root directory are allowed to be served by default. Assuming the codex repository folder is a sibling of the target project to test, the vite config can be modified to temporary allow serving files from outside its root.

// vite.config.js
const { defineConfig } = require( 'vite' );

module.exports = defineConfig( {
	server: {
		fs: {
			/**
			 * Allow serving files from the codex local package.
             * Only files from the dist/ directory should be used
			 */
			allow: [ '../codex/packages/codex/dist' ]
		}
	}
} );

This change should not be pushed to the remote repository.

Unlinking[edit]

To revert your project to use the original Codex version:

/projects/my-node-package$ npm unlink --no-save @wikimedia/codex    # remove the package without removing its original entry in package.json
/projects/my-node-package$ npm install                              # install the package again from the npm registry

See npm-link

Trouble shooting[edit]

VitePress creates a cache dependency directory which isn't updated on unlinking operations. You can just flush its content and the cache will be populated again with the current packages from node_modules.

/projects/my-node-package$ rm -rf docs/.vitepress/cache/deps/

Integrating a Vue prototype into a MW extension[edit]

Pre-steps ( developed in the VitePress sandbox in the prototyping phase )[edit]

This is a backlog of issues found while trying to integrate a Vue component developed with VitePress and Codex into GrowthExperiments. TODO: add links to phab tasks.

  1. Integrate with a MW-compatible i18n system T335277
  2. Meet, at least, the UX excellence level of OOUI version of the implemented component
    1. Adapt component styles and user interactions (eg: swipe) for RTL languages T335371
    2. Image loading performance T335268
    3. Documentation on the component

Steps ( developed in MW in the integration phase )[edit]

  1. Compile the Vue code
  2. Load it through RL
  3. Testing? Regression?
  4. ...