feature/external-link-icon (#320)

* Create base files for new external link functionality

* Updated guidance and refactored javascript code to be more flexible

* Updated guidance and short summary

src/components/_all.scss

@@ -15,6 +15,7 @@
 @import 'hero-search/hero-search';
 @import 'in-page-alert/in-page-alert';
 @import 'in-page-nav/in-page-nav';
+@import 'link/link';
 @import 'link-list/link-list';
 @import 'list-item/list-item';
 @import 'loader/loader';

src/components/link/_guidance.hbs

@@ -0,0 +1,56 @@
+---
+title: Link
+layout: blank-layout.hbs
+---
+
+<h2>Usage</h2>
+
+<p>Link text should be clear and meaningful.</p>
+
+<p>Use links to:</p>
+<ul>
+	<li>navigate between different pages and sections</li>
+	<li>navigate to an external website</li>
+	<li>jump to an element on the same page</li>
+	<li>link to information such as emails or phone numbers</li>
+</ul>
+
+<h3>Links vs. buttons</h3>
+
+<p>While buttons and links are similar, they differ in usage and behaviour.</p>
+
+<ul>
+	<li>Links are used to navigate, directing users to different pages or sections. They are suited for textual content that requires a link to additional information or related resources.</li>
+	<li>Buttons are better suited as interactive elements that trigger actions or perform a specific task when clicked or activated, such as submitting a form, initiating downloads, opening modals or dialog boxes or initiating user interactions within the interface.</li>
+</ul>
+
+<h3>Link icons</h3>
+
+<p>Using icons that convey meaning can enhance the user experience.</p>
+
+<p>Commonly icons used with links:</p>
+
+<ul>
+	<li><strong>External link icon:</strong> to navigate to a different website or web page outside the current domain.</li>
+	<li><strong>Download icon:</strong> to view or download a document, such as a PDF or Word file.</li>
+	<li><strong>Phone icon:</strong> to call or contact a phone number.</li>
+	<li><strong>Email icon:</strong> to open the default email client to compose a new message.</li>
+	<li><strong>Calendar icon:</strong> to link to a calendar, scheduling functionality or an .ical file.</li>
+</ul>
+
+<h3>When to avoid</h3>
+
+<p>Do not:</p>
+
+<ul>
+	<li>overload content with excessive links, instead use only when necessary</li>
+	<li>use generic terms like 'click here', 'see', 'more' or 'more information'</li>
+	<li>use a URL for link text. Use link text that clearly identifies the target of the link</li>
+	<li>make the link text too long. Only link the main words</li>
+	<li>use the same link text for different URLs on the same page</li>
+	<li>use end punctuation. If your link is at the very end of a sentence, make sure that the full stop is not part of the linked text</li>
+</ul>
+
+
+<h2>Accessibility</h2>
+<p>All components are responsive and meet WCAG 2.1 AA accessibility guidelines.</p>

src/components/link/_link.hbs

@@ -0,0 +1,6 @@
+{{#if inline}}<p>
+  Maecenas at risus ullamcorper odio facilisis <a href="#">ultrices et</a> et metus.
+</p>{{/if}}{{#if icon}}<a class="js-link" href="https://digital.nsw.gov.au">{{#if-equals type "download"}}
+  <span class="material-icons nsw-material-icons" title="download file">file_download</span><span>My Link (PDF, 123.45 KB)</span>{{/if-equals}}{{#if-equals type "external"}}
+  <span>My Link</span><span class="material-icons nsw-material-icons" title="(opens in new window)">open_in_new</span>{{/if-equals}}
+</a>{{/if}}

src/components/link/_link.scss

@@ -0,0 +1,40 @@
+.nsw-link {
+  &--button {
+    @include font-size('sm');
+    @include link;
+    background-color: transparent;
+    border: 0;
+    padding: 0;
+
+    &.nsw-small {
+      @include font-size('xs');
+    }
+  }
+
+  &--icon {
+    display: inline-block;
+    font-weight: var(--nsw-font-bold);
+    text-decoration: none;
+
+    span {
+      text-decoration: underline;
+    }
+
+    .nsw-material-icons,
+    svg {
+      font-size: rem(map-get($nsw-icon-sizes, 20));
+      line-height: rem(10px);
+      position: relative;
+      bottom: rem(-5px);
+      text-decoration: none;
+
+      &:first-child {
+        margin-right: rem(4px);
+      }
+
+      &:last-child {
+        margin-left: rem(4px);
+      }
+    }
+  }
+}

src/components/link/index.hbs

@@ -0,0 +1,21 @@
+---
+title: Link
+width: narrow
+tabs: true
+directory: link
+intro: Links are elements that allow you to navigate between different webpages or different sections within the same webpage.
+meta-description: Links are elements that allow you to navigate between different webpages or different sections within the same webpage.
+meta-index: true
+---
+
+{{#>_docs-example separated=true}}
+{{>_link inline="true"}}
+{{/_docs-example}}
+
+{{#>_docs-example separated=true}}
+{{>_link icon="true" type="external"}}
+{{/_docs-example}}
+
+{{#>_docs-example separated=true}}
+{{>_link icon="true" type="download"}}
+{{/_docs-example}}

src/components/link/link.js

@@ -0,0 +1,43 @@
+import { uniqueId } from '../../global/scripts/helpers/utilities'
+
+class ExternalLink {
+  constructor(element) {
+    this.link = element
+    this.uID = uniqueId('external')
+    this.linkIcon = this.link.querySelector('.nsw-material-icons')
+    this.linkIconTitle = this.linkIcon.getAttribute('title')
+    this.linkElement = false
+  }
+
+  init() {
+    this.link.classList.add('nsw-link', 'nsw-link--icon')
+    this.constructor.setAttributes(this.link, {
+      target: '_blank',
+      rel: 'noopener',
+    })
+    this.constructor.setAttributes(this.linkIcon, {
+      focusable: 'false',
+      'aria-hidden': 'true',
+    })
+    this.createElement(this.linkIconTitle)
+  }
+
+  createElement(title) {
+    if (title) {
+      this.linkElement = document.createElement('span')
+      this.linkElement.id = this.uID
+      this.linkElement.classList.add('sr-only')
+      this.linkElement.innerText = title
+      this.link.insertAdjacentElement('afterend', this.linkElement)
+      this.constructor.setAttributes(this.link, {
+        'aria-describedby': this.uID,
+      })
+    }
+  }
+
+  static setAttributes(el, attrs) {
+    Object.keys(attrs).forEach((key) => el.setAttribute(key, attrs[key]))
+  }
+}
+
+export default ExternalLink

src/core/typography/_typography.scss

@@ -210,47 +210,6 @@ a {
   }
 }
 
-.nsw-link {
-  &--button {
-    @include font-size('sm');
-    @include link;
-    background-color: transparent;
-    border: 0;
-    padding: 0;
-
-    &.nsw-small {
-      @include font-size('xs');
-    }
-  }
-
-  &--icon {
-    display: inline-block;
-    font-weight: var(--nsw-font-bold);
-    text-decoration: none;
-
-    span {
-      text-decoration: underline;
-    }
-
-    .nsw-material-icons,
-    svg {
-      font-size: rem(map-get($nsw-icon-sizes, 20));
-      line-height: rem(10px);
-      position: relative;
-      bottom: rem(-5px);
-      text-decoration: none;
-
-      &:first-child {
-        margin-right: rem(4px);
-      }
-
-      &:last-child {
-        margin-left: rem(4px);
-      }
-    }
-  }
-}
-
 .nsw-section-separator {    
   border: 0;
   height: 1px;

src/core/typography/index.hbs

@@ -199,8 +199,8 @@ meta-index: true
 </p>
 <p>
   <a class="nsw-link nsw-link--icon" href="#">
-    <span class="material-icons nsw-material-icons" focusable="false" aria-hidden="true">download</span>
-    <span>Download PDF schedule</span>
+    <span class="material-icons nsw-material-icons" focusable="false" aria-hidden="true">file_download</span>
+    <span>Download PDF schedule (PDF, 123.45 KB)</span>
   </a>
 </p>
 {{/_docs-example}}

src/global/handlebars/layouts/layout.hbs

@@ -14,7 +14,8 @@
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">
-  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/css?family=Material+Icons|Material+Icons+Outlined|Material+Icons+Two+Tone" rel="stylesheet">
+
   <link rel="stylesheet" href="/docs/css/docs.css">
 {{#unless page}}
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/atom-one-light.min.css">

src/main.js

@@ -9,6 +9,7 @@ import GlobalAlert from './components/global-alert/global-alert'
 import Select from './components/select/select'
 import Tooltip from './components/tooltip/tooltip'
 import Toggletip from './components/tooltip/toggletip'
+import ExternalLink from './components/link/link'
 
 if (window.NodeList && !NodeList.prototype.forEach) {
   NodeList.prototype.forEach = Array.prototype.forEach
@@ -43,6 +44,7 @@ function initSite() {
   const multiSelect = document.querySelectorAll('.js-multi-select')
   const tooltip = document.querySelectorAll('.js-tooltip')
   const toggletip = document.querySelectorAll('.js-toggletip')
+  const link = document.querySelectorAll('.js-link')
 
   openSearchButton.forEach((element) => {
     new SiteSearch(element).init()
@@ -104,8 +106,14 @@ function initSite() {
       new Toggletip(element).init()
     })
   }
+
+  if (link) {
+    link.forEach((element) => {
+      new ExternalLink(element).init()
+    })
+  }
 }
 
 export {
-  initSite, SiteSearch, Navigation, Accordion, Tabs, GlobalAlert, Dialog, Filters, FileUpload, Select, Tooltip, Toggletip,
+  initSite, SiteSearch, Navigation, Accordion, Tabs, GlobalAlert, Dialog, Filters, FileUpload, Select, Tooltip, Toggletip, ExternalLink,
 }

src/main.scss

@@ -24,6 +24,7 @@
 @import 'components/hero-search/hero-search';
 @import 'components/in-page-alert/in-page-alert';
 @import 'components/in-page-nav/in-page-nav';
+@import 'components/link/link';
 @import 'components/link-list/link-list';
 @import 'components/list-item/list-item';
 @import 'components/loader/loader';