Overview

Per T344021#9312795, we need to:

• Create and document a standard in the library where we always add specificity when styling a subcomponent
• Add the subcomponent's class as an additional class selector.

Concretely, the latter means that when there's e.g. an Icon component inside the Label component, the Label component currently styles it with &__icon (which expands to .cdx-label__icon), but instead of that we want it to use &__icon.cdx-icon (which expands to .cdx-label__icon.cdx-icon).

See T344021#9312795 for an inventory of which components use which other components (also duplicated in the acceptance criteria below).

Acceptance Criteria

• Document this standard
• Apply it to all components
  • Accordion: Button, Icon
  • ButtonGroup: Button
  • Card: Icon, Thumbnail
  • Checkbox: Label (via binary-input.less)
  • Combobox: Button, Icon, TextInput
  • Dialog: Button
  • InfoChip: Icon
  • InputChip: Button
  • Label: Icon
  • Lookup: TextInput
  • Menu: MenuItem, ProgressBar
  • MenuItem: Icon, Thumbnail
  • Message: Button, Icon
  • Radio: Label (via binary-input.less)
  • SearchInput: Button, TextInput
  • Select: Icon
  • Tabs: Button (cdx-tabs__list__item)
    • Remove cdx-tabs__list__item because this selector is applied to a static HTML <button> - not a CdxButton.
    • Apply specificity to the scroll button (cdx-tabs__scroll-button) which is a CdxButton.
  • TextArea: Icon
  • TextInput: Icon
  • Thumbnail: Icon
  • ToggleButtonGroup: ToggleButton
  • ToggleSwitch: Label
  • TypeaheadSearch: Icon, MenuItem, SearchInput

Resources

• Specifics on CSS Specificity (CSS Tricks)
• Codex contributing code: writing styles
  • Section on "selectors and structure"
• Using your local version of Codex in your local MediaWiki instance

Instructions to test local Codex changes in a MediaWiki instance

Pre-req:

• Open 3 separate editor windows (VSCode) that cd into these repositories: MediaWiki, CodexExample, and Codex
• Run an instance of MediaWiki (instructions found in MediaWiki repo DEVELOPERS.md)
• Install CodexExample extension in MediaWiki
• Use this CodexExample playground branch
  • In CodexExample, checkout the branch by running git checkout css-specificity-staging

Steps:

1. Make changes in the Codex repo
2. In Codex, run npm run -w @wikimedia/codex build to create an optimized production build of Codex. The build process output is stored in /dist/modules/.
3. In MediaWiki core, run cp ../codex/packages/codex/dist/modules/* resources/lib/codex/modules/to copy the files from Codex to MediaWiki core. This copies the local changes from Codex into your local MediaWiki instance. Notice the unstaged changes in MediaWiki core.
4. In the browser that's running MediaWiki on http://localhost:8080, navigate to the CodexExample page /wiki/Special:CodexExample page (http://localhost:8080/wiki/Special:CodexExample)
5. In the CodexExample repo, make changes in this "playground" branch to check for style loading errors in MediaWiki core.

Making changes in CodexExample:

1. Copy code from a component demo eg. Menu with pending state to App.vue in CodexExample.
   • Import components and composables from Codex using require( '../../codex.js' ).
     • Example:const { CdxMenu, CdxTextInput, useGeneratedId, useFloatingMenu } = require( '../../codex.js' );
   • Import icons from Codex using require( '../icons.json' );.
     • Example: const { cdxIconCamera, cdxIconBook, cdxIconClock } = require( '../icons.json' );
2. In extension.json (ref), add the icons, components and composables that are required (or imported).
   • Add the component and composables to "codexComponents" list in extension.json
   • Add icons to the "callbackParam" list in extension.json
3. In extension.json, add the styles to load (after the component loads) to "ext.codexExample.secondThing"
4. Refresh the Special:CodexExample page after changes are made in CodexExample. You'll mainly be working in files, App.vue and extension.json.
5. Check that the selector styles are not being overridden.
6. In the browser console, run mw.loader.load( 'ext.codexExample.secondThing' ) to load the styles of subcomponents and check for any style loading errors

Netlify links to view changes made from this patch

• Codex Demo Sandbox(https://980457--wikimedia-codex.netlify.app/sandbox/)
• Codex(https://980457--wikimedia-codex.netlify.app/components/overview.html)