Banner spec

packages/nimble-components/src/banner/specs/README.md

@@ -0,0 +1,186 @@
+# Banner
+
+## Overview
+
+The banner is a component used to display a persistent notification to a user.
+
+### Background
+
+[Design specification](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/29c405f7-08ea-48b6-973f-546970b9dbab/)
+
+[GitHub issue](https://github.com/ni/nimble/issues/305)
+
+### Non-goals
+
+- Arbitrary HTML content
+- A container component that would enforce design constraints on multiple banners displayed together
+- Limitating length of displayed text and/or truncating text with ellipsis
+
+### Features
+
+- Optionally dismissable
+- Optional link or button (only 1) to perform an action/navigation
+- Distinct designs for banners of type Error, Warning, Info, or Neutral
+
+### Risks and Challenges
+
+None
+
+### Prior Art/Examples
+
+Refer to examples in the "Some examples of screenshots" section of the [GitHub issue](https://github.com/ni/nimble/issues/305).
+
+---
+
+## Design
+
+The banner is a standalone component that spans the width of its containing element, presenting, from left to right, an icon (dependent on Error/Warning/Info type), an optional title, an optional plaintext message, an optional action button or link, and an optional close control. The banner is intended to display short messages (recommended three lines or fewer) that communicate some persistent state or condition.
+
+In this initial implementation, we will not limit the height of the banner. It will grow to fit the text that it is given.
+
+When the user presses the close button, we will hide the banner (and fire a `close` event).
+
+### API
+
+*The key elements of the component's public API surface:*
+
+- *Component Name*: `nimble-banner`
+- *Props/Attrs*:
+  - `heading` - if set, a heading with the specified text is shown to the left of the message. OPEN QUESTION: should we instead use the existing `title` attribute?
+  - `text` - the message text
+  - `prevent-dismiss` - set to hide the close button (attr name taken from Nimble dialog)
+  - `type` - one of `error`, `warning`, `info`, or `neutral` (default)
+  - `action-text` - the text of the action link/button. If unset, no link/button is displayed.
+  - `action-href` - if set, the action element will be a link with the given `href`. (Otherwise, when `action-text` is set, a button element will be displayed.)
+  - `action-button-appearance` - either `outline` or `ghost` (default). When an action button is displayed, this controls the appearance variant.
+  - `close-button-title` - a localized title to give the close button (for a11y purposes)
+- *Methods*
+- *Events*
+  - `close` - fired when the banner is dismissed
+  - `action` - fired when the action button is activated (by mouse or keyboard). This is the intended way for clients to perform an action.
+- *CSS Classes and CSS Custom Properties that affect the component*
+
+### Alternatives
+
+- The text of the banner could be provided as content rather than an attribute. This has the benefit of leaving the door open for us to support more than just plaintext in the future. However, so long as we _don't_ want to support arbitrary HTML, it may have the downside of giving users the wrong idea.
+
+- Instead of configuring the action link/button via attributes, we could allow the user to provide that element as content and slot it in an `action` slot. This would have the following benefits:
+    - allows full configuration of action element (e.g. attributes like `target` on a `nimble-anchor`)
+    - user can add handlers directly to their action element rather than relying on `action` event
+    - easier to support multiple actions in the future
+    - easy to support other kinds of action elements in the future
+
+    However, that flexibility is also a downside. We would no longer have tight control over what the user could show and how it would look.
+
+### Anatomy
+
+```html
+<div class="icon">
+  ${when(x => x.type === 'error', html`<nimble-icon-exclamation-mark></nimble-icon-exclamation-mark>`)}
+  ${when(x => x.type === 'warning', html`<nimble-icon-triangle-filled></nimble-icon-triangle-filled>`)}
+  ${when(x => x.type === 'info', html`<nimble-icon-info></nimble-icon-info>`)}
+</div>
+<div class="text">
+  <span class="heading">
+    ${x => x.heading}
+  </span>
+  ${x => x.text}
+</div>
+${when(x => x.actionText, html`
+  <div class="action">
+    ${when(x.actionHref, html`
+      <nimble-anchor href="${x => x.actionHref}">${x => x.actionText}</nimble-anchor>`
+    )}
+    ${when(!x.actionHref, html`
+      <nimble-button appearance="${x => x.actionButtonAppearance}">${x => x.actionText}</nimble-button>`
+    )}
+  </div>`
+)}
+<div class="close">
+  ${when(x => !x.preventDismiss), html`
+    <nimble-button appearance="ghost" content-hidden>
+      <nimble-icon-xmark slot="start"></nimble-icon-xmark>
+    </nimble-button>`
+  )}
+</div>
+```
+
+### Angular integration
+
+An Angular wrapper will be created for `nimble-banner`. No `ControlValueAccessor` is needed.
+
+`routerLink` will not be supported for the link.
+
+### Blazor integration
+
+Blazor integration for the `nimble-banner` will be provided.
+
+### Visual Appearance
+
+See XD document link at the top of this document.
+
+The biggest issue is that we will have to completely re-style the icons, link, and buttons:
+- Primary icon (error, warning, or info) color is transparent white (in all themes)
+- Action button height is 24px (instead of 32px)
+- Action button hover border color is white (in all themes)
+- Action link color is white (in all themes)
+- Close button is 16px square
+- Close button icon is 8px square
+- Close button hover effect is background color change (transparent white) rather than border
+
+We are not able to directly style some of these elements, because they are in the shadow DOM of  `nimble-icon-*` and `nimble-button`. We will have to resort to overriding Nimble token values, like `--ni-nimble-icon-color` and `--ni-nimble-icon-size`.
+
+---
+
+## Implementation
+
+### States
+
+N/A
+
+### Accessibility
+
+*Consider the accessibility of the component, including:*
+
+- *Keyboard Navigation and Focus*
+    - the action button/link and the close button will be focusable tab stops
+- *Form Input*
+    - N/A
+- *Use with Assistive Technology*
+  - the banner will have the ARIA role of `status`. The role `alert` was considered, but it is too aggressive for the range of banner use cases.
+  - the `status` role has implicit `aria-live` value of `polite`
+  - if the user supplies a title, we will set `aria-label` to that value
+  - the user may specify `aria-label` on the `nimble-banner`, but it is not required
+- *Behavior with browser configurations like "Prefers reduced motion"*
+  - N/A
+
+### Globalization
+
+N/A
+
+### Security
+
+N/A
+
+### Performance
+
+N/A
+
+### Dependencies
+
+N/A
+
+### Test Plan
+
+Unit tests and visual comparison tests will be created that exercise all features.
+
+### Tooling
+
+N/A
+
+### Documentation
+
+Storybook stories will be created.
+
+---
+## Open Issues