Bring main up-to-date

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [9.4.1](https://github.com/UN-OCHA/common_design/compare/v9.4.0...v9.4.1) (2024-05-15)
+
+
+### Bug Fixes
+
+* **style:** apply some default styles to field_group details/summary elements ([6947971](https://github.com/UN-OCHA/common_design/commit/6947971342b897187d3319fd5060010f84df2e9c))
+* **style:** OCHA Services separator should inherit color ([4801b3e](https://github.com/UN-OCHA/common_design/commit/4801b3e455b4fbf6175b855e6180627702a0b2e4))
+* **style:** pixel push for mandate logo ([f9a4da5](https://github.com/UN-OCHA/common_design/commit/f9a4da588e3c72656c8f9160dc8bb25f8286d30d))
+
+
 ## [9.4.0](https://github.com/UN-OCHA/common_design/compare/v9.3.4...v9.4.0) (2024-03-19)
 
 ### Features

README.md

@@ -6,44 +6,40 @@ This theme provides a starting point for OCHA's Drupal websites. By installing t
 * **Common Footer:** Navigation, social links, legal info.
 * **Common SVG Icons:** a subset of [OCHA Humanitarian Icons][ocha-icons]
 
-It provides the following theming tools that you should leverage in order to maintain the high standards for accessibility that our organization strives to meet:
+  [ocha-icons]: https://brand.unocha.org/d/xEPytAUjC3sH/icons
 
-* JavaScript dropdowns which do not require jQuery or any framework.
-* Common Design frontend components
+## Getting started
 
-  [ocha-icons]: https://brand.unocha.org/d/xEPytAUjC3sH/icons
+1. **Do not modify the base-theme.** Follow the setup guide in the [sub-theme README][subtheme-readme].
+2. For Twig debug and local development see [Disable Drupal 8+ caching during development][drupal-caching].
+
+  [subtheme-readme]: https://github.com/UN-OCHA/common_design/blob/develop/common_design_subtheme/README.md
+  [drupal-caching]: https://www.drupal.org/node/2598914
 
 ## Drupal utilities
 
 * normalize-css library is included in [Drupal core][normalize] and we depend on it.
 * jQuery is [available in Drupal core][core], but the Common Design does not depend on it. It gets loaded only once it is needed.
 * [hidden.module.css][hidden] is included in Drupal core to provide utility classes that hide content in an accessible manner.
 
-  [normalize]: https://git.drupalcode.org/project/drupal/-/blob/9.5.x/core/assets/vendor/normalize-css/normalize.css
-  [core]: https://git.drupalcode.org/project/drupal/-/blob/9.5.x/core/core.libraries.yml
-  [hidden]: https://git.drupalcode.org/project/drupal/-/blob/9.5.x/core/modules/system/css/components/hidden.module.css
+  [normalize]: https://git.drupalcode.org/project/drupal/-/blob/10.4.x/core/assets/vendor/normalize-css/normalize.css
+  [core]: https://git.drupalcode.org/project/drupal/-/blob/10.4.x/core/core.libraries.yml
+  [hidden]: https://git.drupalcode.org/project/drupal/-/blob/10.4.x/core/modules/system/css/components/hidden.module.css
 
-## Additional components
+## Additional tools
 
 * Typography defaults
 * Component library. See [Common Design demo][cd-demo] for live examples.
-  * Components that can be attached as Drupal libraries to twig templates.
-  * Component namespacing by way of [Components module][components-module].
-  * Docs available in [Components README][components-readme] and [each component][components-used] has some docs in the base theme.
+  * Components that can be attached as [Drupal Libraries][drupal-libraries] to Twig templates.
+  * Namespacing by way of [Components module][components-module].
+  * Docs available in [Libraries README][libraries-readme] and [each Drupal Library][libraries-list] has some docs in the base theme.
 * Favicons and OCHA branded assets based on https://brand.unocha.org
 
   [cd-demo]: https://web.brand.unocha.org/demo
+  [drupal-libraries]: https://www.drupal.org/docs/theming-drupal/adding-assets-css-js-to-a-drupal-theme-via-librariesyml
   [components-module]: https://www.drupal.org/project/components
-  [components-readme]: https://github.com/UN-OCHA/common_design/blob/main/components/README.md
-  [components-used]: https://github.com/UN-OCHA/common_design/blob/main/components/
-
-## Getting started
-
-1. Follow the setup guide in the [sub-theme README][subtheme-readme].
-2. For Twig debug and local development see [Disable Drupal 8+ caching during development][drupal-caching].
-
-  [subtheme-readme]: https://github.com/UN-OCHA/common_design/blob/main/common_design_subtheme/README.md
-  [drupal-caching]: https://www.drupal.org/node/2598914
+  [libraries-readme]: https://github.com/UN-OCHA/common_design/blob/develop/libraries/README.md
+  [libraries-list]: https://github.com/UN-OCHA/common_design/blob/develop/libraries/
 
 ## Single Directory Components
 
@@ -59,7 +55,6 @@ If you can't or don't want to use SDC, read the [CSS](#css) and [JS](#js) sectio
 
 For managing CSS, use [Drupal Libraries][drupal-libraries] to create components made of vanilla CSS/JS files, store them in a component-specific folder inside `libraries`, and attach them to the appropriate Twig template so that they only appear on pages where needed.
 
-  [drupal-libraries]: https://www.drupal.org/docs/theming-drupal/adding-assets-css-js-to-a-drupal-theme-via-librariesyml
 
 ## JS
 
@@ -75,37 +70,41 @@ this.methodName();
 Drupal.behaviors.cdDropdown.methodName();
 ```
 
-Using `this` works for most functions except ones which are assigned to event listeners. For those, we have prefixed all of them with the word `handle` — and despite being contained within the same Behavior, you'll need to reference internal functions using the full Behavior name (see second example above, as if it were outside your Behavior).
+Using `this` works for most functions except ones which are assigned to event listeners. For those, we have prefixed all of them with the word `handle`. In order to easily use other methods defined in your Behavior, you'll need to bind `this` manually. [There are examples of the process in the CD Dropdown][bind-this].
+
+If you don't manually bind `this`, then you have to use the full object as if you were in the global global scope. See code:
+
+  [bind-this]: https://github.com/UN-OCHA/common_design/blob/8c7b648a86c2f7293d96f3fefbd9345c83d843aa/libraries/cd-dropdown/cd-dropdown.js#L9-L14
 
 ```js
 (function (Drupal) {
   'use strict';
 
   Drupal.behaviors.exampleBehavior = {
     attach: function (context, settings) {
+      // ✅ Manually bind `this` before it gets used.
+      this.handleClick = this.handleClick.bind(this);
+
       // Assign handleClick as an event listener. When assigning the handler
       // it is correct to prefix the method name with `this`
       document.addEventListener('click', this.handleClick);
     },
 
-    sendAlert: function (message) {
+    showAlert: function (message) {
       window.alert(message);
     },
 
     handleClick: function (ev) {
-      // ❌ WRONG:
-      //
-      // Inside this event listener handler, we do not have access to the
-      // Behavior object as `this` so this.sendAlert() will not be defined
-      // and the following error will occur:
+      // ✅ after binding `this`
       //
-      // Uncaught TypeError: this.sendAlert is not a function
-      this.sendAlert(ev.target);
+      // Shorthand will work as long as the .bind(this) command was run inside
+      // the `attach` method.
+      this.showAlert(ev.target);
 
-      // ✅ CORRECT:
+      // ❌ without binding `this`
       //
-      // Referencing the Behavior as defined in Drupal object will work.
-      Drupal.behaviors.exampleBehavior.sendAlert(ev.target);
+      // If we hadn't bound `this` inside `attach` then it would be long-winded:
+      Drupal.behaviors.exampleBehavior.showAlert(ev.target);
     }
   };
 })(Drupal);
@@ -126,6 +125,11 @@ If you do create a new template, use one from the base-theme as a guide. They ha
 
   [hide-content]: https://www.drupal.org/docs/accessibility/hide-content-properly
 
+## Print
+
+Using `@media print` should be sufficient in most cases, unless there is a specific reason to have a specific print.css stylesheet (e.g. used by [Snap Service][snap-classes]). Refer to `_print.scss` for basic rules.
+
+  [snap-classes]: https://github.com/UN-OCHA/tools-snap-service?tab=readme-ov-file#using-snap-service-on-your-website
 
 ## Fonts
 

common_design.info.yml

@@ -36,6 +36,8 @@ regions:
 libraries-extend:
   core/drupal.dropbutton:
     - common_design/cd-dropbutton
+  core/drupal.message:
+    - common_design/messages
 
 libraries-override:
   core/modernizr:

common_design.libraries.yml

@@ -8,6 +8,15 @@ global-styling:
   dependencies:
     - common_design/cd-core
 
+# Style status messages when they come via bigpipe.
+# @see https://www.drupal.org/project/drupal/issues/3456176
+messages:
+  css:
+    component:
+      libraries/cd-alert/cd-alert.css: {}
+  js:
+    js/messages.js: {}
+
 # Roboto Condensed and Slab.
 # @see https://brand.unocha.org/d/xEPytAUjC3sH/visual-identity#/basics/fonts/advanced-users
 fonts-advanced:

common_design.theme

@@ -499,11 +499,13 @@ function common_design_preprocess_html(&$vars) {
   $status_code = \Drupal::requestStack()->getCurrentRequest()->attributes->get('exception');
 
   // Add body classes.
-  if ($status_code && !is_a($status_code, 'ParamNotConvertedException') && $status_code->getStatusCode() == 404) {
-    $vars['attributes']['class'][] = 'path-error path-error--404';
-  }
-  if ($status_code && !is_a($status_code, 'ParamNotConvertedException') && $status_code->getStatusCode() == 403) {
-    $vars['attributes']['class'][] = 'path-error path-error--403';
+  if ($status_code && !is_a($status_code, 'ParamNotConvertedException')) {
+    if ($status_code->getStatusCode() == 404) {
+      $vars['attributes']['class'][] = 'path-error path-error--404';
+    }
+    if ($status_code->getStatusCode() == 403) {
+      $vars['attributes']['class'][] = 'path-error path-error--403';
+    }
   }
 
   // Add a script to detect whether javascript is enabled or not and then

common_design_subtheme/README.md

@@ -19,7 +19,7 @@ Refer to [Drupal 9+ Theming documentation][theming-docs] for more information.
 3. In the Drupal Admin, go to Appearance, find **OCHA Common Design sub theme** and select **Enable and set default**.
 4. Customize the `name`/`description` fields of the sub-theme's info file if you wish.
 5. Rebuild the cache.
-6. Edit the sub-theme's `css/brand.css` to pick your site's palette. No other modifications are necessary.
+6. Edit the sub-theme's `css/brand.css` to pick your site's palette. No other modifications are necessary. The header/footer plus all components will adopt your new colors.
 
 
 ### Customise the logo
@@ -48,7 +48,7 @@ Replace the favicon in the theme's root, and the homescreen icons in `img/` with
 
 ### Customise colours
 
-Change the CSS Vars in `css/brand.css` and save the file. Sass is no longer available in CD v8.
+Change the CSS Vars in `css/brand.css` and save the file. Sass is no longer available in CD v8 and newer.
 
 
 ### Customise icons
@@ -94,8 +94,7 @@ Core and CD base-theme libraries [can be extended with small customizations][lib
 
 Override theme preprocess functions by copying from `common_design.theme` and editing as needed. hen copying, the **function name will always need to be modified** from `common_design_` to `common_design_subtheme_`.
 
-Refer to [common_design README][cd-readme] for
-general details about base-theme and instructions for compilation. There should be no need to use Sass in the sub-theme anymore.
+Refer to [common_design README][cd-readme] for general details about base-theme and instructions for compilation. There should be no need to use Sass in the sub-theme anymore.
 
   [cd-readme]: https://github.com/UN-OCHA/common_design/blob/main/README.md#ocha-common-design-for-drupal-9
 
@@ -119,7 +118,7 @@ npm run e2e -- --debug
 # argument. It will parse all of the describe() blocks and only run tests when
 # it matches the string you supply.
 
-# All tests that include 'OCHAServicesDropdown'.
-npm run e2e -- -t 'OCHAServicesDropdown'
+# All tests that include 'OCHAServices'.
+npm run e2e -- -t 'OCHAServices'
 
 ```