@eeacms/volto-eea-design-system 0.9.5 → 1.0.0-alpha.2

package/website/docs/webdev/md_components/maps_components/usage_markdown.md

@@ -0,0 +1,64 @@
+### Static
+
+There are five main design principles in map design. 
+
+- legibility 
+- visual contrast 
+- figure-ground organization 
+- hierarchical organization, and  
+- balance 
+
+Together these principles form a system for seeing and understanding the relative importance of the content in the map and on the page.  
+
+What are the qualities of a good map? 
+
+- clear idea of what the map is trying to demonstrate 
+- easy to interpret legend or key 
+- good use of symbols to demonstrate a clear point
+- good sources/metadata 
+- clear features not overcrowded
+
+#### Styles  
+
+- do not use underlined text! This is difficult for low-vision users to read and indicates a possible hyperlink 
+- italics should be used as little as possible, for water labels and short labels only 
+- bolding of fonts is a good way to call out features, but avoid it for continuous, readable text
+- although ALL CAPS labels stand out, they are harder to read and should be used sparingly
+
+#### Map Objects  
+
+- avoid overlapping points or annotations, when possible. Try to place them offset from a line 
+- there should be visible whitespace between symbols; touching symbols blend together for users with low vision 
+- there should be a 2x size difference in levels of information  
+
+#### Colors 
+
+- **use a limited color palette.** Limited color palette works the best for all UIs, and map UI is not an exception. It’s much easier to create visual harmony with a limited color palette. You should use between 10 to 12 colors for a full-body color palette, depending on the complexity of your map. Choose colors for individuals with visual impairments such as color-blindness (i.e. don’t use red-green color schemes)  
+- **try to use the same hue for similar features.** For example, features related to transportation (bus stops, railway stations, etc.) should share the same hue. The same hue will help users to decode visual elements without reading text, and this will help you to create a more cohesive UI. 
+- **always consider accessibility.** Many people have limited color vision, so you also need to take this into account when selecting colors to ensure that you have a proper contrast ratio
+
+#### Text  
+
+- choose fonts that have a variety of styles, such as bold, extra bold, italic, bold italic light, etc to differentiate between different kinds of features on your map  
+- use one version of fonts for the map body and one for the explainer text outside the map
+
+### Interactive Maps 
+
+Interactive maps are high risk, high reward. Highly interactive maps can be too difficult for new users, yet they can also allow users to learn and explore at their own pace. It is always important to test designs on multiple people with varying degrees of technical expertise to see how they interact differently with the layout. Interactive map design should reflect what the cartographer is trying to convey (beauty vs. function) and never sacrifice visual hierarchy or great styling for interactivity. 
+
+Tips for designing effective interactive maps:  
+
+- simplify the interface  
+- panels should be the minimum possible size so they don’t clutter the space 
+- don’t innovate to the point where users don’t know what to do  
+- use panel opacity and margins to help them blend with your basemap and look cohesive  
+- leave space for the maps to be used on mobile devices. This means avoiding permanent panels  
+
+#### Pop-ups and markers 
+
+- keep pop-ups concise 
+- only one pop-up on the screen at a time (generally) 
+- cluster markers for better readability  
+- use a legend when you have multiple types of markers  
+- remove unnecessary padding and margins from popups 
+- use a slight shadow to “lift” pop-ups off the map 

package/website/docs/webdev/md_components/media_container_image_components/api_markdown.md

@@ -0,0 +1,25 @@
+## API
+
+<AccordionJSDoc />
+
+## Setup
+
+There are 2 ways to initialise the component.
+
+### Automatic
+
+Add `data-ecl-auto-init="Accordion"` attribute to component's markup:
+
+```html
+<div class="ecl-accordion" data-ecl-accordion data-ecl-auto-init="Accordion">
+  ...
+</div>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-accordion` on the page:

package/website/docs/webdev/md_components/media_container_image_components/showcase_markdown.md

@@ -0,0 +1,7 @@
+import Iframe from '../iframe_component.mdx';
+
+## Image
+
+<Iframe id='components-media-container-image--default' height="500"> </Iframe>
+
+

package/website/docs/webdev/md_components/media_container_image_components/usage_markdown.md

@@ -0,0 +1,10 @@
+ Images must have natural snapshots that show unique situations.
+
+### Do’s
+-	use stylistic tools such as light, perspective, color, focus and composition to tell stories that are authentic and believable.
+-	the content of the photographs should be positive, optimistic, natural, realistic, warm, and welcoming. Framing should be playful and feel spontaneous
+### Don’ts
+-	do not use images that are too dark or do not have enough contrast
+-	do not use overlaying gradients
+-	images that are too static or that appear too symmetrical should not be used
+-	do not Use images that are over exposed or over saturated

package/website/docs/webdev/md_components/message_components/api_markdown.md

@@ -0,0 +1,30 @@
+## API
+
+<MessageJSDoc />
+
+## Setup
+
+There are 2 ways to initialise the component.
+
+### Automatic
+
+Add `data-ecl-auto-init="Message"` attribute to component's markup:
+
+```html
+<div
+  role="alert"
+  class="ecl-message ecl-message--info"
+  data-ecl-message
+  data-ecl-auto-init="Message"
+>
+  ...
+</div>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-message` on the page:

package/website/docs/webdev/md_components/message_components/showcase_markdown.md

@@ -0,0 +1,17 @@
+import Iframe from '../iframe_component.mdx';
+
+## Default
+<Iframe id='components-message--default' height="120"> </Iframe>
+
+## Success
+<Iframe id='components-message--success' height="120"> </Iframe>
+
+## Warning
+<Iframe id='components-message--warning' height="120"> </Iframe>
+
+## Error
+<Iframe id='components-message--error' height="120"> </Iframe>
+
+## Info
+<Iframe id='components-message--info' height="120"> </Iframe>
+

package/website/docs/webdev/md_components/message_components/usage_markdown.md

@@ -0,0 +1,22 @@
+Messages component contains important information to alert users to take a certain actions.
+
+### Do's
+
+- keep the message brief and clear
+- use consistent messages for the same information/success/warning/error throughout your site
+
+### Don'ts
+
+- overuse messages - users may ignore them and they can get in the way of a user completing their task
+- write messages that are neutral. For example, instead of _The postal code you entered is invalid,_ the message should say _Please enter a valid postal code_
+
+### When to use
+
+- when the information is essential to convey to the users in order to go to the next step
+- success message: the user has performed an action which was successfully completed
+- warning message: the user needs to know about the potential dangers of completing their task (for example: "you are about replace/erase your data")
+- error message: the user tried to perform an action that failed because of a problem (for example: a file could not be uploaded because it wasn't the correct type of file)
+
+### When not to use
+
+- don't use to show non critical information

package/website/docs/webdev/md_components/modal_components/api_markdown.md

@@ -0,0 +1,36 @@
+## API
+
+<MenuJSDoc />
+
+## Force close
+
+For javascript based pages or applications, you can use the css class `ecl-menu--forced-close` to manually close the menu on desktop view (on mobile a close function is already provided).
+Feel free to add/remove this class when needed.
+
+Note: for a better display, you may want to remove/add the css class `ecl-menu--transition` when manually changing the close/open status of the menu.
+
+## Setup
+
+There are 2 ways to initialise the component.
+
+### Automatic
+
+Add `data-ecl-auto-init` attribute to component's markup
+
+```html
+<nav class="ecl-menu" data-ecl-menu data-ecl-auto-init="Menu">...</nav>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-menu` on the page:
+
+```js
+var elt = document.querySelector('[data-ecl-menu]');
+var menu = new ECL.menu(elt);
+menu.init();
+```

package/website/docs/webdev/md_components/modal_components/showcase_markdown.md

@@ -0,0 +1,3 @@
+import Iframe from '../iframe_component.mdx';
+
+<Iframe id='components-modal--default' > </Iframe>

package/website/docs/webdev/md_components/modal_components/usage_markdown.md

@@ -0,0 +1,11 @@
+Modals appear on top of the main content and require user interaction. This dialog disables the main content until the user explicitly interacts with the modal dialog.
+
+### Do’s
+-	use modal dialogs for important warnings, to prevent or correct critical errors
+-	use modal dialogs to request the user to enter information critical to continuing the current process
+-	modal dialogs can be used to fragment a complex workflow into simpler steps
+
+### Don’ts
+-	do not use modal dialogs for nonessential information that is not related to the current user flow
+-	avoid modal dialogs that interrupt high-stake processes
+-	avoid modal dialogues for complex decision making that require additional sources of information unavailable in the modal

package/website/docs/webdev/md_components/page_header_components/api_markdown.md

@@ -0,0 +1,25 @@
+## API
+
+<AccordionJSDoc />
+
+## Setup
+
+There are 2 ways to initialise the component.
+
+### Automatic
+
+Add `data-ecl-auto-init="Accordion"` attribute to component's markup:
+
+```html
+<div class="ecl-accordion" data-ecl-accordion data-ecl-auto-init="Accordion">
+  ...
+</div>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-accordion` on the page:

package/website/docs/webdev/md_components/page_header_components/showcase_markdown.md

@@ -0,0 +1,5 @@
+import Iframe from '../iframe_component.mdx';
+
+<Iframe id='components-page-header--default' height="500" > </Iframe>
+
+<Iframe id='components-page-header--default&args=image:false' height="500" > </Iframe>

package/website/docs/webdev/md_components/page_header_components/usage_markdown.md

@@ -0,0 +1,30 @@
+The page header component provides users the context of the page. It is always placed just below the site header. 
+
+### Anatomy
+
+| **Components**                                                                                                                                                                                                             | **Mandatory** | **Optional** |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------ |
+| **Page title**                                                                                                                                                                                                                   | yes           | no         |
+| **Meta( content type, published date, modified date, reading time )**                                                                                                                                                                                                             | no           | yes          |
+| **Download - Bookmark actions**                                                                                                                                                                                                           | no            | yes          |
+| **Breadcrumb**<br />Breadcrumb component provides information on the page and its relationship to the site's hierarchy and structure.<br />It is optional if your website's navigational structure has less than 3 levels. | no            | yes          |
+
+
+### Do's
+
+- ensure the pages contain all the components and elements in the anatomy table above
+- always use a page header when building your internal pages
+- when choosing a background image, make sure it highlights the main object related to the content, and it is meaningful
+
+### Don'ts
+
+- don't use more than one page header per page
+- do not use a background image unless there is a communication need, as it might be a distraction
+
+### When to use
+
+- to highlight the topic of the page, or to show important information about the page
+
+### When not to use
+
+- page header is not used for homepage of the website

package/website/docs/webdev/md_components/pagination_components/api_markdown.md

@@ -0,0 +1,36 @@
+## API
+
+<MenuJSDoc />
+
+## Force close
+
+For javascript based pages or applications, you can use the css class `ecl-menu--forced-close` to manually close the menu on desktop view (on mobile a close function is already provided).
+Feel free to add/remove this class when needed.
+
+Note: for a better display, you may want to remove/add the css class `ecl-menu--transition` when manually changing the close/open status of the menu.
+
+## Setup
+
+There are 2 ways to initialise the component.
+
+### Automatic
+
+Add `data-ecl-auto-init` attribute to component's markup
+
+```html
+<nav class="ecl-menu" data-ecl-menu data-ecl-auto-init="Menu">...</nav>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-menu` on the page:
+
+```js
+var elt = document.querySelector('[data-ecl-menu]');
+var menu = new ECL.menu(elt);
+menu.init();
+```

package/website/docs/webdev/md_components/pagination_components/showcase_markdown.md

@@ -0,0 +1,3 @@
+import Iframe from '../iframe_component.mdx';
+
+<Iframe id='components-pagination--default' > </Iframe>

package/website/docs/webdev/md_components/pagination_components/usage_markdown.md

@@ -0,0 +1,17 @@
+Pagination component is the control to navigate through multiple pages.
+
+### Do's
+
+- place the pagination below the list of items
+
+### Don'ts
+
+- don't replace this component with an "infinite scrolling" feature
+
+### When to use
+
+- to show long lists otherwise redundant scrolling in one page
+
+### When not to use
+
+- don't use to break unrelated content on different pages

package/website/docs/webdev/md_components/popup_components/api_markdown.md

@@ -0,0 +1,36 @@
+## API
+
+<MenuJSDoc />
+
+## Force close
+
+For javascript based pages or applications, you can use the css class `ecl-menu--forced-close` to manually close the menu on desktop view (on mobile a close function is already provided).
+Feel free to add/remove this class when needed.
+
+Note: for a better display, you may want to remove/add the css class `ecl-menu--transition` when manually changing the close/open status of the menu.
+
+## Setup
+
+There are 2 ways to initialise the component.
+
+### Automatic
+
+Add `data-ecl-auto-init` attribute to component's markup
+
+```html
+<nav class="ecl-menu" data-ecl-menu data-ecl-auto-init="Menu">...</nav>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-menu` on the page:
+
+```js
+var elt = document.querySelector('[data-ecl-menu]');
+var menu = new ECL.menu(elt);
+menu.init();
+```

package/website/docs/webdev/md_components/popup_components/showcase_markdown.md

@@ -0,0 +1,9 @@
+import Iframe from '../iframe_component.mdx';
+
+## Button Popup
+
+<Iframe id='components-popup--button-popup'height="400" > </Iframe>
+
+## Image Popup
+
+<Iframe id='components-popup--image-popup'height="400" > </Iframe>

package/website/docs/webdev/md_components/popup_components/usage_markdown.md

@@ -0,0 +1,15 @@
+A popup (also known as an overlay) is a window or dialog that appears on top of the page content.
+A popup can be classified according to two dimensions:
+- whether the user can interact with the rest of the page, and it is called 'Modal' when the content on the page is disabled until the user explicitly interacts with the overlay or 'Nonmodal' when users can still interact with the background content (for example, by selecting links or tapping buttons) while the overlay remains visible
+- whether the background is dimmed the popup is called a 'Lightbox'
+
+
+### Do’s
+-	present the content in the popup when it’s contextually relevant to the user
+-	if you must present critical information (e.g., important warnings to prevent or correct errors) in a popup, be sure to show only one at a time
+
+### Don’ts
+-	do not show a popup before the main page content loads
+-	do not display a popup right after the user logs in
+-	you should not ask for feedback before people have done anything meaningful
+-	do not show multiple popups one after another

package/website/docs/webdev/md_components/progress_components/api_markdown.md

@@ -0,0 +1,36 @@
+## API
+
+<MenuJSDoc />
+
+## Force close
+
+For javascript based pages or applications, you can use the css class `ecl-menu--forced-close` to manually close the menu on desktop view (on mobile a close function is already provided).
+Feel free to add/remove this class when needed.
+
+Note: for a better display, you may want to remove/add the css class `ecl-menu--transition` when manually changing the close/open status of the menu.
+
+## Setup
+
+There are 2 ways to initialise the component.
+
+### Automatic
+
+Add `data-ecl-auto-init` attribute to component's markup
+
+```html
+<nav class="ecl-menu" data-ecl-menu data-ecl-auto-init="Menu">...</nav>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-menu` on the page:
+
+```js
+var elt = document.querySelector('[data-ecl-menu]');
+var menu = new ECL.menu(elt);
+menu.init();
+```

package/website/docs/webdev/md_components/progress_components/showcase_markdown.md

@@ -0,0 +1,13 @@
+import Iframe from '../iframe_component.mdx';
+
+## Default
+
+<Iframe id='components-progress--default'height="120" > </Iframe>
+
+## Progress with Value
+
+<Iframe id='components-progress--progress-with-value' height="120"> </Iframe>
+
+## Custom Color
+
+<Iframe id='components-progress--custom-color'height="120" > </Iframe>

package/website/docs/webdev/md_components/progress_components/usage_markdown.md

@@ -0,0 +1,9 @@
+Progress indicators tell users that more time is needed to process the last user action (for instance, to load a file, or to install a new update), and how much time remains.
+
+### Do’s
+-	use a progress indicator for any action that takes longer than about 1.0 second
+-	use Looped animation only for fast actions. The animated-spinner icon is an example of this common progress indicator. This indicator should be used for actions that take between 2-10 seconds
+-	percent-done animation: Use for actions that take 10 seconds or more.
+
+### Don’ts
+-	do not use static progress indicators

package/website/docs/webdev/md_components/quote_components/api_markdown.md

@@ -0,0 +1,27 @@
+## API
+
+<TableJSDoc />
+
+## Setup
+
+Add `data-ecl-table-sort-toggle` attribute on table headings for which you want to activate sorting.
+
+There are 2 ways to initialise the component for sort table.
+
+### Automatic
+
+Add `data-ecl-auto-init="Table"` attribute to component's markup:
+
+```html
+<table data-ecl-auto-init="Table" class="ecl-table">
+  ...
+</table>
+```
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-table` on the page:

package/website/docs/webdev/md_components/quote_components/showcase_markdown.md

@@ -0,0 +1,13 @@
+import Iframe from '../iframe_component.mdx';
+
+## Default
+
+<Iframe id='components-quote--default'height="700" > </Iframe>
+
+
+<br/><br/>
+
+## Reversed
+
+<Iframe id='components-quote--reversed' height="700"> </Iframe>
+

package/website/docs/webdev/md_components/quote_components/usage_markdown.md

@@ -0,0 +1,8 @@
+Quote is a key phrase, quotation, or excerpt that has been pulled from an article and used as a page layout graphic element, serving to entice readers into the article or to highlight a key topic.
+
+
+### Dont's
+
+- Do not use more than one quote per page
+- Do not use long text or job title
+

package/website/docs/webdev/md_components/radio_components/api_markdown.md

@@ -0,0 +1,34 @@
+## API
+
+<SelectJSDoc />
+
+## Setup
+
+There are 2 ways to initialise the select multiple component.
+
+### Automatic
+
+Add `data-ecl-auto-init="Select"` attribute to component's markup:
+
+Use the `ECL` library's `autoInit()` (`ECL.autoInit()`) when your page is ready or other custom event you want to hook onto.
+
+### Manual
+
+Get target element, create an instance and invoke `init()`.
+
+Given you have 1 element with an attribute `data-ecl-select-multiple` on the page:
+
+```js
+var elt = document.querySelector('[data-ecl-select-multiple]');
+var select = new ECL.Select(elt);
+select.init();
+```
+
+It's also possible to use the `Select`'s `autoInit` method and pass specific labels for the element:
+
+```js
+var select = ECL.Select.autoInit(
+  document.querySelector('[data-ecl-select-multiple]'),
+  { defaultText: 'string', searchText: 'string', selectAllText: 'string' },
+);
+```

package/website/docs/webdev/md_components/radio_components/showcase_markdown.md

@@ -0,0 +1,15 @@
+import Iframe from '../iframe_component.mdx';
+
+## Default
+
+<Iframe id='components-forms-radio--default' > </Iframe>
+
+
+## Invalid
+
+<Iframe id='components-forms-radio--invalid' height="400"> </Iframe>
+
+
+## Binary
+
+<Iframe id='components-forms-radio--binary' > </Iframe>

package/website/docs/webdev/md_components/radio_components/usage_markdown.md

@@ -0,0 +1,26 @@
+Radio buttons provides a selection with two or more options. Only one option can be selected.
+
+### Do's
+
+- use labels as click targets (clicking the label will select that option)
+- group related fields
+- order logically (e.g. ages 18-25, ages 25-35, ages, 35-50, over 65)
+- indicate whether the input group is optional - _if it's mandatory, have a neutral option (e.g. other, n/a) selected by default_
+- make use of helper text if there are further directions or hints the users may need in completing their goal
+- write specific and clear error messages, so users understand how to address the error
+
+### Don'ts
+
+- don't add them without grouping first
+- don't nest elements under radio buttons - keep all the options on the same level
+
+### When to use
+
+- when you have under 10 items
+- when users need to select options or toggle settings, for example
+- in forms with multiple non-exclusive options (e.g. search filters)
+- only one selection can be made
+
+### When not to use
+
+- avoid when more than one option can be selected - use checkboxes instead

package/website/docs/webdev/md_components/searchbox_components/usage_markdown.md

@@ -0,0 +1,15 @@
+Search lets users assert independence from websites' attempt to direct how they use it. Therefore, many users go straight to the homepage search function. 
+
+Search is also users' escape hatch when they are stuck in navigation. When they cannot find a reasonable place to go next, they often turn to the site's search function. This is why you should make search available from every page on the site; you cannot predict where users will be when they decide they are lost. 
+
+### Do's 
+
+- **use placeholder text.** Placeholder text provides context as to what can be searched and describes the action of the input
+
+- **use a magnifying glass icon.** The magnifying glass is universally recognized as a symbol for search and one which users can easily identify 
+
+- **provide a button to submit search queries.** Inputs should be accessible. Ensure users can return results using their keyboard as well as clicking a button or the magnifying glass icon 
+
+- **consider the search icon position.** In most cases, it is beneficial to place the Icon to the right of placeholder text. This allows the Icon to act as the submit button and makes more sense hierarchically as queries are entered first, and results returned after
+
+- **use input widths which are appropriate for the typical query length.** The width of the Input field should be wide enough to contain the typical search query. If an Input field is too narrow, it results in scrolling and decreases usability. It is recommended to use a minimum width of 27 characters