Skip to content

Commit

Permalink
Duplicate styles, components, patterns for brands
Browse files Browse the repository at this point in the history
  • Loading branch information
@GeorgeEverett
GeorgeEverett committed Nov 10, 2023
1 parent 0418d72 commit 95a9fb8
Show file tree
Hide file tree
Showing 270 changed files with 31,014 additions and 43 deletions.
23 changes: 12 additions & 11 deletions src/www/pages/components/index.njk
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
{% extends "www/_layouts/layout-left-pane.njk" %}
{% set pageTitle = "Components" %}

{% block content %}
<p>Components are reusable parts of the user interface that have been made to support a variety of
applications.</p>

<p>Individual components can be used in multiple different patterns and contexts. For example, the
text input component can be used to ask for an email address, a National Insurance number or someone’s name.</p>
<p>If you are using the WMCA Design System Prototype Kit or have WMCA Design System Frontend included in your build, the
coded examples provided will render exactly as they do inside the Design System.</p>
{% extends "www/_layouts/layout-left-pane.njk" %}
{% set pageTitle = "Components" %}
{% set ds = 'wmca' %}

{% block content %}
<p>Components are reusable parts of the user interface that have been made to support a variety of
applications.</p>

<p>Individual components can be used in multiple different patterns and contexts. For example, the
text input component can be used to ask for an email address, a National Insurance number or someone’s name.</p>
<p>If you are using the WMCA Design System Prototype Kit or have WMCA Design System Frontend included in your build, the
coded examples provided will render exactly as they do inside the Design System.</p>
{% endblock %}
1 change: 1 addition & 0 deletions src/www/pages/mc/components/index.njk
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
{% extends "www/_layouts/layout-left-pane.njk" %}
{% set pageTitle = "Components" %}
{% set ds = 'mc' %}

{% block content %}
<p>Components are reusable parts of the user interface that have been made to support a variety of
Expand Down
135 changes: 135 additions & 0 deletions src/www/pages/mc/components/patterns/autocomplete/index.njk
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
{% extends "www/_layouts/layout-left-pane.njk" %}
{% set pageTitle = "Autocomplete" %}
{% set section="Patterns" %}
{% set ds = 'wmca' %}

{# Imports #}
{% from "wmcads/patterns/autocomplete/_autocomplete.njk" import wmcadsAutocomplete %}
{% from "www/_partials/component-example/component-example.njk" import compExample %}

{% block content %}
{# About #}
<h2>About</h2>
{# What #}
<h3>What does it do?</h3>
<p>
The autocomplete component is an input field that offers the user text suggestions as they type.<br/>
This is often done by hitting an API endpoint with the users query when the user has finished typing.
</p>
<p>
The autocomplete pattern is a combination of the <a href="/components/form-elements/" title="Input component" target="_self" class="ds-link">input</a> and <a href="/components/loader/" title="Loader component" target="_self" class="ds-link">loader</a> components.
</p>
{# When #}
<h3>When to use it?</h3>
<ul>
<li>As a progressive enhancement to make a users journey shorter/easier when searching</li>
<li>When you have a smaller data set/list that is quick to query</li>
<li>When you want to ensure the user submits a relevant query/value</li>
</ul>
{# When not #}
<h3>When not to use it?</h3>
<ul>
<li>When you have a massive set of data, instead you should have an input/search that shows results after submission.</li>
<li>Don't use this component as if it is a search box. Autocomplete is to suggest a value to a user via it's results not act as a results page for a search.</li>
</ul>

<hr><br><br>
{# Default #}
<h2>Default state</h2>
<p>In its default state, the autcomplete component is made up of a text input with a search icon.</p>
<p>For best practice, ensure that the placeholder and aria-label describes what the autocompletes intended purpose is.</p>
<p>Notice that there is also a <code class="ds-website-inline-code">ds-loader</code> component nested within the autocomplete, more on that in the next section.</p>
{{
compExample([
wmcadsAutocomplete({
id: "autoComplete",
query: ''
})
]) | trim
}}


<br><br>
{# Loading #}
<h2>Loading</h2>
<p>
When a user types in a query, you may want to have some code that hits an API or gets the data/suggestions for the autocomplete from somewhere. To help users understand that they need to wait for something we can change the autocomplete to a loading state.
We do this by adding the class <code class="ds-website-inline-code">ds--is-loading</code> to the top level of the autocomplete (this is the only difference between the loading state and default state code snippets).
</p>
<p>As mentioned in the previous section, there is a <code class="ds-website-inline-code">ds-loader</code> component nested in the autocomplete.<br/> When adding the <code class="ds-website-inline-code">ds--is-loading</code> class, it will hide the search icon and show the loading spinner in it's place.</p>
<p>Below is an example of how the autocomplete looks when a user has typed in 'My query' and is waiting for autocomplete suggestions to load.</p>

<p><strong>It is good practice to:</strong></p>
<ul>
<li>Show loading state when waiting for data to load</li>
<li>Let the user finish typing before you fetch autocomplete suggestions (add a debounce)</li>
<li>Add the ds-is--loading class as soon as you are fetching data</li>
</ul>
{{
compExample([
wmcadsAutocomplete({
id: "autoCompleteQuery",
query: 'My query',
loading: true
})
]) | trim
}}


<br><br>
{# Results #}
<h2>Suggestions</h2>
<p>The final state of the autocomplete is showing the suggestions.</p>
<p>You'll notice there is a new section in the code snippet called <code class="ds-website-inline-code">ds-autocomplete-suggestions</code>, this should be shown/visible when your API/data has loaded the suggestions.</p>
<p><strong>It's good practice to:</strong></p>
<ul>
<li>Show the suggestions in an unordered list</li>
<li>Ensure there is a title tag on the <code class="ds-website-inline-code">.ds-autocomplete-suggestions__li</code> describing further information about the suggestion</li>
<li>Ensure there is a <code class="ds-website-inline-code">tabindex="0"</code> attribute on the <code class="ds-website-inline-code">.ds-autocomplete-suggestions__li</code> to allow users to tab through the results with a keyboard</li>
</ul>

<h3>Default (text)</h3>
<p>The most commonly used suggestions will be displayed as text only.</p>
<p>
<strong>It is good practice to:</strong>
</p>
<ul>
<li>Bold characters that match the users query</li>
</ul>

{{
compExample([
wmcadsAutocomplete({
id: "autoCompleteSuggestions",
showSuggestions: true,
textSuggestions: true,
query: 'My query'
})
]) | trim
}}

{# With disruption indicator #}
<h3>With disruption indicator</h3>
<p>
This autocomplete is combined with the <a href="/components/disruption-indicators/" title="Disruption indicator component" target="_self" class="ds-link">medium / normal - disruption indicator component</a>.
</p>
<p>You will notice that the suggestions are much bigger than text only results, and have an overflow scrollbar. This scrollbar will appear if the height of the suggestion container goes over a certain height.</p>
<p>
As you can see from the code snippet, the main <code class="ds-website-inline-code">ds-autocomplete-suggestions</code> and <code class="ds-website-inline-code">ds-autocomplete-suggestions__li</code> classes are prevelant on the ul and li elements. Within the li element we have nested the disruption indicator component whilst also using the <a href="/styles/utility-classes/" title="wmcads grid system" target="_self" class="ds-link">wmcads grid</a>. This gives enough flexibility to style the suggestions to how we want, find out more in the next section.
</p>
{{
compExample([
wmcadsAutocomplete({
showSuggestions: true,
query: 'x15'
})
]) | trim
}}

<h3>Customising suggestions</h3>
<p>There are many ways in which you can show the suggestions, as the autocomplete component has been built in a way that the suggestion results can be custom styled to how you like.</p>
<p>
As long as you have the ul element with the class <code class="ds-website-inline-code">ds-autocomplete-suggestions</code> which contains a direct child li element that has the class <code class="ds-website-inline-code">ds-autocomplete-suggestions__li</code> then you can fully customise how you want the suggestions to look.
</p>

{% endblock %}

0 comments on commit 95a9fb8

Please sign in to comment.