Handle SASS deprecations

README.md

@@ -9,10 +9,11 @@ This module is maintained by the PD Digital Team. We're a friendly crew that wel
 ## Features
 
 + ✅ Implements all components from the NSW Design System v3
-+ ✅ Branding: full support for Masterbrand, Co-brand and Independent entities within [the NSW branding guidelines](https://digitalnsw.github.io/nsw-design-system/core/logo/index.html).
-+ ✅ BSD-3 licensed. Can be used in all projects, including proprietary projects.
++ ✅ Branding: full support for Masterbrand, Co-brand and Independent entities within [the NSW branding guidelines](https://designsystem.nsw.gov.au/core/logo/index.html).
++ ✅ [Aboriginal colour palette support](./docs/en/102_aboriginal_colour_palette.md)
++ ✅ **BSD-3 licensed**. Can be used in all projects, including proprietary projects.
 + ✅ Completely extendable using standard development practices via Silverstripe templating, configuration and Composer module management
-+ ✅ Standard page layouts based on [template examples](https://digitalnsw.github.io/nsw-design-system/templates/index.html)
++ ✅ Standard page layouts based on [template examples](https://designsystem.nsw.gov.au/templates/index.html)
 + ✅ Integrates our supported [Elemental content blocks](https://github.com/silverstripe/silverstripe-elemental)
 + ✅ Includes our [Silverstripe content authoring boilerplate](https://github.com/nswdpc/silverstripe-content-boilerplate) containing our supported content authoring tools.
 + ✅ Form building - supports all Silverstripe form fields plus our supported form field extensions

docs/en/001_index.md

@@ -14,7 +14,7 @@ After installation, you will need to build the frontend assets using one of our
 1. Add/update theme configuration
 1. Run the standard Silverstripe dev/build when required
 
-### 1. Build the frontend assets 
+### 1. Build the frontend assets
 
 You can build the frontend in a variety of ways, depending on your build system toolkit.
 
@@ -69,6 +69,26 @@ When the module is updated or installed `composer run-script build-nswds` should
 
 Both script targets run ./build.sh which expects npm to be available.
 
+
+### Development tools
+
+If you use a tool such as Lando for your development, add a tooling command to assist with automation of the build process:
+
+```yml
+tooling:
+  buildnswds:
+    service: node
+    description: Build the NSW Design System using build.sh
+    cmd: ./vendor/nswdpc/waratah/build.sh
+```
+
+And build:
+```sh
+lando buildnswds
+```
+
+You can also build the frontend assets by invoking the build.sh script in the lando `post-start` command.
+
 #### Loading CSS and JS assets
 
 Once built, assets are available in the `vendor/nswdpc/waratah/themes/nswds/app/frontend/dist` location. This path is vendor-exposed in `composer.json` and automatically exposed when the module is installed.
@@ -102,7 +122,7 @@ SilverStripe\View\SSViewer:
     - '$default'
 ```
 
-If you have a custom theme in your project that provides custom templates, specify that before `nswdpc/waratah:nswds` 
+If you have a custom theme in your project that provides custom templates, specify that before `nswdpc/waratah:nswds`
 
 ```yaml
 # app/_config/theme.yml

docs/en/003_filter_form.md

@@ -1,8 +1,8 @@
 # Filter form
 
-Turn a standard Silverstripe form into a [NSWDS Filter Form](https://digitalnsw.github.io/nsw-design-system/components/filters/index.html) quickly using the `FilterForm` trait.
+Turn a standard Silverstripe form into a [NSWDS Filter Form](https://designsystem.nsw.gov.au/components/filters/index.html) quickly using the `FilterForm` trait.
 
-How your application filters requests and displays results is entirely up to you. The recommended result layout is a [list item](https://digitalnsw.github.io/nsw-design-system/templates/search/filters.html) template.
+How your application filters requests and displays results is entirely up to you. The recommended result layout is a [list item](https://designsystem.nsw.gov.au/templates/search/filters.html) template.
 
 ## Via a custom form and template
 
@@ -22,7 +22,7 @@ class SomeFilterForm extends Form
 {
 
     use \NSWDPC\Waratah\Traits\FilterFormTrait;
-    
+
     /**
      * Clear link used for filter form
      */
@@ -50,15 +50,15 @@ use SilverStripe\Forms\TextField;
  * This controller provides a form to help with searching for something
  */
 class MyController extends \PageController {
-    
+
     /**
      * @var array
      */
     private static $allowed_actions = [
         'SomeFilterForm',
         'doSearch'
     }
-    
+
     /**
      * Do the filtered search
      */
@@ -104,7 +104,7 @@ class MyController extends \PageController {
         );
         return $form;
     }
-    
+
 }
 ```
 

docs/en/100_branding.md

@@ -1,10 +1,12 @@
 # Branding
 
-The module supports branding and co-branding as set by the [NSW Government branding guidelines](https://digitalnsw.github.io/nsw-design-system/)
+> IMPORTANT: do not copy the `nswds` theme to your project. This will cause technical debt in your project.
+
+The module supports branding and co-branding as set by the [NSW Government branding guidelines](https://designsystem.nsw.gov.au/)
 
 To add branding within these guidelines, some once-off setup steps are needed.
 
-Your project should have a custom theme:
+If your project has a custom theme, it should be declared with the highest priority.
 
 ```yaml
 # app/_config/theme.yml
@@ -13,14 +15,17 @@ Name: project-theme
 ---
 SilverStripe\View\SSViewer:
   themes:
+    ## if your project has a custom theme, add the theme name (it will be in the themes directory in the project root)
     - 'project-theme'
+    ## in vendor/nswdpc/waratah/themes
     - 'nswdpc/waratah:nswds'
+    ## fallback template usage (see Silverstripe theming documentation)
     - '$default'
 ```
 
-In the above configuration, it's expected your theme templates are present in `themes/project-theme` (you can call your theme anything you want).
+In the above configuration, it's expected your theme templates are present in `themes/project-theme` (you can call your theme anything you want, 'project-theme' is just an example).
 
-The `project-theme` has a higher priority than this module's theme, meaning your project can override any template provided by this module. This is quite powerful but remember that doing so may cause your project to miss out on improvements, fixes and features added to this module.
+In this example, the `project-theme` has a higher priority than this module's `nswds` theme, meaning your project can override any template provided by the `nswds` theme. This is quite powerful but remember that doing so may cause your project to miss out on improvements, fixes and features added to this module.
 
 ## Branding version
 
@@ -73,7 +78,7 @@ waratah-branding/
     frontend/
         src/
             js/
-                app.js -> this will be imported and run after `window.NSW.initSite();` 
+                app.js -> this will be imported and run after `window.NSW.initSite();`
             scss/
                 defaults.scss -> this will be included as the first CSS component in the build
                 app.scss -> this will be included as the last CSS component in the build
@@ -101,14 +106,33 @@ initMyProject();
 
 ### CSS overrides
 
-> 💡 NSW Government websites should follow the NSW Government branding guidelines
+> 💡 NSW Government websites should follow the [NSW Government branding guidelines](https://designsystem.nsw.gov.au/).
 
 You can override default SCSS settings by adding them to `waratah-branding/frontend/src/defaults.scss` or `waratah-branding/frontend/src/app.scss` in your project.
 
 The file `defaults.scss` will load prior to the main NSWDS scss and allows you to set default settings.
 
 The file `app.scss` will load after the main NSWDS scss and allows you to incorporate CSS for your own components.
 
+As of nswdpc/waratah v2.1, to use the nsw-design-system mixins and functions you must declare usage of them in your project SCSS files:
+
+```scss
+// Example
+// e.g. app.scss
+@use '../../../vendor/nswdpc/waratah/themes/nswds/app/frontend/node_modules/nsw-design-system/src/global/scss/base/mixins' as nswdsMixins;
+@use '../../../vendor/nswdpc/waratah/themes/nswds/app/frontend/node_modules/nsw-design-system/src/global/scss/base/functions' as nswdsFunctions;
+
+.myapp-selector {
+  @include nswdsMixins.breakpoint('lg') {
+    margin-top: nswdsFunctions.rem(8px);
+  }
+
+  &__box {
+    padding: nswdsFunctions.rem(16px);
+  }
+}
+```
+
 ## Building
 
 After adding a component you should [build the requirements again](./001_index.md). Watch for any errors and fix as required.

docs/en/101_advanced_configuration.md

@@ -1,6 +1,6 @@
 # Advanced Configuration
 
-> ℹ️ Standard template override information can be found in [branding documentation](./100_branding.md).
+> Standard template override information can be found in [branding documentation](./100_branding.md).
 
 :warning: It's assumed you know what you are doing when modifying these options. If you find a bug with it, please let us know in the Github issues.
 
@@ -18,7 +18,7 @@ NSWDPC\Waratah\Models\DesignSystemConfiguration:
 The system will look for built app.js and app.css in `vendor/me/some-module/themes/my-specific-theme/app/frontend/dist`
 
 ## Even more advanced configuration:
- 
+
 Ignore all asset and requirement loading using `frontend_provided: true`. It's assumed you are providing your own method of delivering the built NSW Design System assets.
 
 ```yaml

docs/en/102_aboriginal_colour_palette.md

@@ -0,0 +1,48 @@
+# Aboriginal Colour Palette
+
+As of [nsw-design-system 3.21.0](https://github.com/digitalnsw/nsw-design-system/releases/tag/v3.21.0), an Aboriginal colour palette is provided, with examples at [designsystem.nsw.gov.au](https://designsystem.nsw.gov.au/docs/content/design/theming.html#aboriginal-palette).
+
+When implementing a palette, please follow the guidelines at the above link, including colour contrast rules to maintain accessibility.
+
+## Implementing a palette
+Implementing a colour palette is easy. Using the Bush Plum palette as a guide:
+
+### 1. Add a palette CSS file
+
+In the waratah-branding/frontend/src directory created in your project, add a `palette.scss` file
+
+### 2. Include it in the app.scss file
+
+In the app.scss alongside this file, include the palette:
+
+```scss
+// waratah-branding/frontend/src/app.scss
+@use './palette';
+```
+
+### 3. Add the palette colours
+
+```scss
+// waratah-branding/frontend/src/palette.scss
+// Bush Plum: https://designsystem.nsw.gov.au/templates/theming/full-page.html?palette=aboriginal&color=Bush+Plum
+:root {
+  --nsw-brand-dark: var(--nsw-aboriginal-palette-bush-plum);
+  --nsw-brand-light: var(--nsw-aboriginal-palette-dusk-purple);
+  --nsw-brand-supplementary: var(--nsw-aboriginal-palette-spirit-lilac);
+  --nsw-brand-accent: var(--nsw-aboriginal-palette-orange-ochre);
+  --nsw-brand-accent-light: var(--nsw-aboriginal-palette-sunset-orange);
+  --nsw-link: var(--nsw-aboriginal-palette-bush-plum);
+  --nsw-visited: var(--nsw-aboriginal-palette-spirit-lilac);
+  --nsw-hover: rgba(var(--nsw-aboriginal-palette-bush-plum-rgb), 0.1);
+  --nsw-active: rgba(var(--nsw-aboriginal-palette-bush-plum-rgb), 0.2);
+  --nsw-focus: var(--nsw-aboriginal-palette-orange-ochre);
+}
+```
+
+All palette colours can be found at [_aboriginal-palette.scss - Github](https://github.com/digitalnsw/nsw-design-system/blob/master/src/global/scss/settings/_aboriginal-palette.scss) with example colour groups at [theme examples - designsystem.nsw.gov.au](https://designsystem.nsw.gov.au/templates/theming/full-page.html?palette=aboriginal).
+
+### 4. Build the frontend
+
+Use one of the documented build options to build the frontend.
+
+As `waratah-branding/frontend/src/app.scss` is added last in the build process, the palette selection will override the default NSW Government branding.

src/Extensions/BaseElementExtension.php

@@ -5,13 +5,10 @@
 use NSWDPC\Waratah\Models\DesignSystemConfiguration;
 use NSWDPC\Waratah\Forms\SectionSelectionField;
 use NSWDPC\Waratah\Traits\DesignSystemSelections;
-use SilverStripe\Assets\Image;
-use SilverStripe\AssetAdmin\Forms\UploadField;
 use SilverStripe\ORM\DataExtension;
 use SilverStripe\Forms\FieldList;
 use SilverStripe\Forms\DropdownField;
 use SilverStripe\Forms\CheckboxField;
-use SilverStripe\View\Requirements;
 
 /**
  * Provide additional elemental integration with DS
@@ -150,7 +147,7 @@ public function updateCMSFields(FieldList $fields)
                         'nswds.BACKGROUND_EXAMPLE',
                         'Example default section backgrounds are available at {exampleURL}',
                         [
-                            'exampleURL' => 'https://digitalnsw.github.io/nsw-design-system/core/section/index.html'
+                            'exampleURL' => 'https://designsystem.nsw.gov.au/core/section/index.html'
                         ]
                     )
                 ),
@@ -174,7 +171,7 @@ public function updateCMSFields(FieldList $fields)
                         'nswds.VERTICAL_SPACING_EXAMPLE',
                         'Spacing examples are available at {exampleURL}',
                         [
-                            'exampleURL' => 'https://digitalnsw.github.io/nsw-design-system/core/section/index.html'
+                            'exampleURL' => 'https://designsystem.nsw.gov.au/core/section/index.html'
                         ]
                     )
                 )->setEmptyString(_t('nswds.SELECT_OPTION', 'Select an option')),
@@ -197,7 +194,7 @@ public function updateCMSFields(FieldList $fields)
 
     /**
      * Return an array of available backgrounds
-     * See: https://nswdesignsystem.surge.sh/styles/section/index.html
+     * See: https://designsystem.nsw.gov.au/core/section/index.html
      */
     protected function getBackgrounds(): array
     {
@@ -221,7 +218,7 @@ protected function getSupportedBackground(string $bg): string
 
     /**
      * Return the nswds background value or an empty value if not supported
-     * https://digitalnsw.github.io/nsw-design-system/core/section/index.html
+     * https://designsystem.nsw.gov.au/core/section/index.html
      * Use by a template as $Background
      * Invert is automatically added when a dark BG is selected
      */

src/Extensions/BreadcrumbExtension.php

@@ -2,13 +2,7 @@
 
 namespace NSWDPC\Waratah\Extensions;
 
-use SilverStripe\Core\Injector\Injector;
-use SilverStripe\Core\Config\Config;
 use SilverStripe\ORM\DataExtension;
-use SilverStripe\Forms\FieldList;
-use SilverStripe\Forms\DropdownField;
-use SilverStripe\Forms\TextareaField;
-use SilverStripe\Forms\CheckboxField;
 
 /**
  * Provide an extension to allow pages to override aspects of Breacrumb-ing

src/Extensions/DesignSystemAssetExtension.php

@@ -7,12 +7,7 @@
 use SilverStripe\Control\Director;
 use SilverStripe\Core\Config\Config;
 use SilverStripe\Core\Extension;
-use SilverStripe\Core\Injector\Injector;
-use SilverStripe\Core\Manifest\ResourceURLGenerator;
-use SilverStripe\View\ArrayData;
 use SilverStripe\View\Requirements;
-use SilverStripe\View\ThemeResourceLoader;
-use SilverStripe\View\SSViewer;
 
 /**
  * Provide NSW Design System asset requirement functionality

src/Extensions/ElementBannerExtension.php

@@ -4,13 +4,10 @@
 
 use NSWDPC\Waratah\Forms\HeroBannerBrandSelectionField;
 use SilverStripe\ORM\DataExtension;
-use DNADesign\Elemental\Models\BaseElement;
 use SilverStripe\AssetAdmin\Forms\UploadField;
-use SilverStripe\Assets\Image;
 use SilverStripe\Forms\FieldList;
 use SilverStripe\Forms\DropdownField;
 use SilverStripe\Forms\TextField;
-use SilverStripe\Forms\CheckboxField;
 use SilverStripe\Forms\HTMLEditor\HTMLEditorField;
 use gorriecoe\Link\Models\Link;
 use gorriecoe\LinkField\LinkField;

src/Extensions/ElementSectionNavigationExtension.php

@@ -6,6 +6,7 @@
 use SilverStripe\ORM\DataExtension;
 use SilverStripe\Forms\FieldList;
 use SilverStripe\Forms\DropdownField;
+use SilverStripe\ORM\ArrayList;
 use SilverStripe\ORM\DataList;
 
 /**
@@ -96,14 +97,22 @@ public function getColumns(): ?string
     /**
      * Return the section navigation sorted by the Sort order in SiteTree
      */
-    public function getSortedSectionNavigation(): ?\SilverStripe\ORM\DataList
+    public function getSortedSectionNavigation(): DataList|ArrayList|null
     {
         $list = $this->getOwner()->getSectionNavigation();
-        if ($list instanceof DataList) {
-            return $list->sort('Sort');
+        if ($list instanceof DataList || $list instanceof ArrayList) {
+            return $list->sort(['Sort' => 'ASC']);
+        } else {
+            return null;
         }
+    }
 
-        return null;
+    /**
+     * Template method for self::getSortedSectionNavigation()
+     */
+    public function SortedSectionNavigation(): DataList|ArrayList|null
+    {
+        return $this->getSortedSectionNavigation();
     }
 
     /**

src/Extensions/FormFieldExtension.php

@@ -4,7 +4,6 @@
 
 use SilverStripe\Core\Extension;
 use SilverStripe\Forms\CompositeField;
-use SilverStripe\Forms\FormField;
 use SilverStripe\Forms\ListboxField;
 
 /**

src/Extensions/IframeVideoExtension.php

@@ -3,8 +3,6 @@
 namespace NSWDPC\Waratah\Extensions;
 
 use SilverStripe\Core\Extension;
-use NSWDPC\Elemental\Models\FeaturedVideo\GalleryVideo;
-use NSWDPC\Elemental\Models\FeaturedVideo\ElementFeaturedVideo;
 use SilverStripe\View\Requirements;
 
 /**