npm package: @pegakit/pk-component-notifications
Description: Notifications are used to communicate news or announcement information to the user.
Author: Salem Ghoweri
Latest version: 0.1.1

## Overview:
- **Twig Template:** `source/_patterns/02-molecules/notifications/notification.twig`
  - **Template Dependencies**:
    - Icon atom
    - D8 Attributes object (via the Pattern Lab Data Transform plugin OR via our create_attribute Twig extension)
- **Sass Component:** `source/styles/pegakit-ui/06-components/_components.notifications.scss`
- **JavaScript Module:** none currently but that'll change w/ these updates)

### PegaKit CSS Framework Dependencies:
  - **01-settings**
    - Global settings (ex. `$global-border-radius`, `$spacing-unit`)
    - Color swatches (ex. `green, light`)
  - **02-tools**
    - Font weight mixin   (ex. `@include font-weight(bold);`)
    - Spacing mixin (ex. `@include spacing(medium);`)
    - Color palette mixin (ex. `@include palette(green, light);`)
  - **03-generic**
    - All (default UI Component dependency)
  - **04-elements**
    - All (default UI Component dependency)
  - **05-objects**
    - Icon object
  - **06-components**
    - None
  - **07-themes**
    - All (default UI Component dependency)
  - **08-utilities**
    - All (default UI Component dependency)

### PegaKit Staging link(s)
- Master (aka pk-legacy): https://patterns.pega.com/?p=viewall-molecules-notifications
- Develop: https://patterns-dev.pega.com/?p=viewall-molecules-notifications
- Accounts: https://patterns-dev.pega.com/branches/accounts-safe/?p=viewall-molecules-notifications
- Blog: https://patterns-dev.pega.com/branches/feature/pega-blog--FED-updates-v2/?p=viewall-molecules-notifications
- Pega Academy:
https://patterns-dev.pega.com/branches/feature/pega-academy/?p=viewall-molecules-notifications
- ChaCha (Broken): https://patterns-dev.pega.com/branches/feature/www-redesign-ch/?p=viewall-molecules-notifications













## Things to keep in mind:
- Mobile first!
- Close button: reminder: keep minimum tappable target area in mind.
- Flexible in height (don't set anything relating to height or min/max height)
- Exact position of close button shouldn't need to get re-adjusted if the padding value inside the notification component changes.
- Sometimes needs to be full width, other times not.
- Need to account for the fact that we already have 6 completely separate, not centrally maintained / versioned versions of this already in PegaKit / out in the wild.



























# Front-end Breakout

## General
1. Move the existing Notification twig template + Sass partial into a single component-specific folder structure. Basically, all the front-end files relating to notifications should end up living in a single place, which should make versioning significantly easier.
  - Update the PegaKit build process if necessary.
  - Keep file types into separate folders for the time being

Before:
```
./source
├── _patterns
|   └── 02-molecules
|      └── notifications
|         ├── notification.twig
|         └── examples
├── styles/pegakit-ui
|   └── 06-components
|      └── _components.notifications.scss
└── scripts
    └── components
       └── notifications/index.js (doesn't currently exist)
```

After:
```
./source
├── _patterns
|   └── 02-molecules
|      └── notifications
|         ├── twig

|         ├── notification.twig
|         └── examples
├── styles/pegakit-ui
|   └── 06-components
|      └── _components.notifications.scss
└── scripts
    └── components
       └── notifications/index.js (doesn't currently exist)
```



### Templates updates
1. Version the existing component (v0.1.0, as is) via Lerna

2. Update the existing template parameters so everything is nested under the `notification` namespace (ex. the notification_button.text and parameter should instead be set via notification.button_text (< 15min)
  ```
  {% include "@molecules/notifications/notification.twig" with {
    notification: {
      button_text: '...',
      text: '...'
    }
  } %}
```

3. The Notification component's Twig template should be updated to use the D8 friendly Attributes object (~15min)

4. Update the template to abstractly handle the different template options / available parameters. (< 15min)**

For example. currently the `caution` UI status gets applied via the `c-notification--caution` class being passed in.

We need to update the template so that we can simply set the status via a `status` parameter and internally the component will validate that the value is OK + decide which class(es) it needs to apply. As a reference, our semi-recently updated button component does something along the lines of:

```
{# button.twig #} 
{% set button_styles = ['positive', 'flat', 'subtle', 'featured'] %}
{% set button_classes = [
  'c-button',
  button.style in button_styles ? 'c-button--' ~ button.style : '',
  ...
] %}

{# page.twig #}
{% include "@atoms/buttons/button.twig" with {
  button: {
    style: 'flat'
  }
} %}
```


4. Rename the currently unused `notification_button.hide` parameter to `can_close` which can be set to T/F. (< 15min)**


5. Example variations in Pattern Lab should be updated to use the same class convention as well. (< 15min)


6. The Icon twig include used in this component:
  a. should be using the updated icon 'size' parameter -- the current class version is deprecated. (< 15min)
  b. should be setting the c-notification--close class via the icon template's attributes class[] array (and it should be removed from the `classes` string parameter) (< 15min)
  

7. Add a new `center` T/F layout option to the notification template. Should be set to false by default.**


8. Update the existing link/button sub-component (the UI used for dismissing the notification, if enabled).
  a. Add in the appropriate `js-` prefixed JavaScript hook class for the JavaScript module we'll be adding
  b. Change from being a <a> tag to being a <button>
  c. add the `type="button"` and `tabindex="0"` attributes
  d. Replace the `<span>` with the visually hidden text inside to instead just be an aria-label on the button itself.
  
  
9. Update the notification component's outer container itself to be accessible.
  a. Add in the following HTML attributes: `tabindex="0" aria-live="assertive" role="alertdialog"`




** All of the above changes / parameter options should be documented in a component-specific markdown file. See Component options below:

## Component options (placeholder example)
Any of these options can be set when the Notification template is included. [Learn more](javascript.md#component-configuration)

| Option | Value | Default | Description |
| --- | --- | --- | --- |
| `close` | CSS selector | `.js-notification__button` | The element to dismiss the notification. |
| `close` | CSS selector | `.js-notification__button` | The element to dismiss the notification. |
| `animation` | Boolean, String | `false` | ['none', 'fade-in', 'slide-in']. |


## Style modifiers
There are several style modifiers available. Just add one of the following classes to apply a different look.

| Class               | Description                                                |
|---------------------|------------------------------------------------------------|
| `.c-notification--error`  | Indicates an important or error message. |
| `.c-notification--success` | Indicates success or a positive message. |
| `.c-notification--warning` | Indicates a message containing a warning. |


# Sass updates
1. Update the margin-bottom logic to handle situations where we may or may not want a margin-bottom value set. If NOT the last child in a container = margin-bottom: 16px?
2. change default background color to white? Need to move the blue background variation to something else
3. move padding from main .c-notification container to .c-notification__text
4. Update the `c-notification__button` styling:
  ```
  width: 44px;
  height: 44px;
  display: inline-block;
  cursor: pointer;
  float: right;
  position: relative;
  z-index: 10; // Any z-index so clicking / tapping hits the target vs getting interfered w/ by the `.c-notification__text` container.
  ```
5. Add overflow hidden to the outer c-notification container




### New JavaScript Module








### Out in the wild examples:
- http://foundation.zurb.com/sites/docs/v/5.5.3/components/alert_boxes.html
- https://codepen.io/joe-watkins/pen/PNMGeZ
- https://tympanus.net/Development/NotificationStyles/bar-slidetop.html#
- https://getuikit.com/v2/docs/notify.html
- https://github.com/govau/uikit/tree/master/packages/page-alerts
- http://foundation.zurb.com/sites/docs/callout.html
- http://materializecss.com/dialogs.html
- https://v4-alpha.getbootstrap.com/components/alerts/#examples