From 924db34cdef43ebf848e8b1079ab254246c0d2ba Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Fri, 20 Jan 2023 11:15:51 -0600 Subject: [PATCH 01/12] Initial draft --- .../src/banner/specs/README.md | 167 ++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 packages/nimble-components/src/banner/specs/README.md diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md new file mode 100644 index 0000000000..5e95ec5435 --- /dev/null +++ b/packages/nimble-components/src/banner/specs/README.md @@ -0,0 +1,167 @@ +# 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. + +### 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. +- *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* + +### Anatomy + +```html +
+ ${when(x => x.type === 'error', html``)} + ${when(x => x.type === 'warning', html``)} + ${when(x => x.type === 'info', html``)} +
+
+ + ${x => x.heading} + + ${x => x.text} +
+
+ ${when(x => x.actionText && x.actionHref, html` + ${x => x.actionText}` + )} + ${when(x => x.actionText && !x.actionHref, html` + ${x => x.actionText}` + )} +
+
+ ${when(x => !x.preventDismiss), html` + + + ` + )} +
+``` + +### 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 will be created that exercise all features. + +### Tooling + +N/A + +### Documentation + +Storybook stories will be created. + +--- +## Open Issues \ No newline at end of file From e1d2594d0597f8c3ea33b356d236c47483f6c3fe Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Wed, 25 Jan 2023 11:18:52 -0600 Subject: [PATCH 02/12] stash --- packages/nimble-components/src/banner/specs/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index 5e95ec5435..d6857d4b0b 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -77,13 +77,13 @@ The banner is a standalone component that spans the width of its containing elem ${x => x.actionText}` )} -
+
${when(x => !x.preventDismiss), html` ` )} -
+
``` ### Angular integration From 2d4907f9ef6afe405a97e8f07b553dbbed04e4d2 Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Wed, 25 Jan 2023 12:02:47 -0600 Subject: [PATCH 03/12] Updates --- .../src/banner/specs/README.md | 37 ++++++++++++++----- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index d6857d4b0b..c2758f1683 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -36,6 +36,10 @@ Refer to examples in the "Some examples of screenshots" section of the [GitHub i 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:* @@ -49,12 +53,25 @@ The banner is a standalone component that spans the width of its containing elem - `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 @@ -69,14 +86,16 @@ The banner is a standalone component that spans the width of its containing elem ${x => x.text} -
- ${when(x => x.actionText && x.actionHref, html` - ${x => x.actionText}` - )} - ${when(x => x.actionText && !x.actionHref, html` - ${x => x.actionText}` - )} -
+${when(x => x.actionText, html` +
+ ${when(x.actionHref, html` + ${x => x.actionText}` + )} + ${when(!x.actionHref, html` + ${x => x.actionText}` + )} +
` +)}
${when(x => !x.preventDismiss), html` @@ -153,7 +172,7 @@ N/A ### Test Plan -Unit tests will be created that exercise all features. +Unit tests and visual comparison tests will be created that exercise all features. ### Tooling From cebfe912a445fffbb888ea7f04c7db6ae2d615b7 Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Thu, 26 Jan 2023 15:30:15 -0600 Subject: [PATCH 04/12] Updates --- .../src/banner/specs/README.md | 64 +++++++------------ 1 file changed, 22 insertions(+), 42 deletions(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index c2758f1683..1f005c7c69 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -14,7 +14,7 @@ The banner is a component used to display a persistent notification to a user. - 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 +- Limiting length of displayed text and/or truncating text with ellipsis ### Features @@ -38,7 +38,7 @@ The banner is a standalone component that spans the width of its containing elem 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). +When the user presses the close button, we will hide the banner (`display:none`) and fire a `close` event. ### API @@ -46,62 +46,44 @@ When the user presses the close button, we will hide the banner (and fire a `clo - *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? + - `heading` - if set, a heading with the specified text is shown to the left of the message. - `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. + - `severity` - one of `error`, `warning`, `info`, or undefined (default) - `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. +- *Slots* + - `title` - for the title/header text + - (default) - for the primary message text + - `action` - for the action button/link - *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. +We only formally support spans of text in the `title` and default slots, but we will not explicitly prevent other HTML from being slotted there. The `action` slot only expects `nimble-button` or `nimble-anchor`, and we will use the CSS `::slotted()` pseudo-element to remove all but those two element types. We will not explicitly prevent multiple elements from being slotted in the `action` slot, though we formally only support one. ### Anatomy ```html
- ${when(x => x.type === 'error', html``)} - ${when(x => x.type === 'warning', html``)} - ${when(x => x.type === 'info', html``)} + ${when(x => x.severity === 'error', html``)} + ${when(x => x.severity === 'warning', html``)} + ${when(x => x.severity === 'info', html``)}
- - ${x => x.heading} - - ${x => x.text} + +
-${when(x => x.actionText, html` -
- ${when(x.actionHref, html` - ${x => x.actionText}` +
+ +
+ ${when(x => !x.preventDismiss), html` + + + ` )} - ${when(!x.actionHref, html` - ${x => x.actionText}` - )} -
` -)} -
- ${when(x => !x.preventDismiss), html` - - - ` - )} +
``` @@ -109,8 +91,6 @@ ${when(x => x.actionText, html` 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. From 412c1723a801a214541376cc3bee593e72ee56e3 Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Thu, 26 Jan 2023 16:00:40 -0600 Subject: [PATCH 05/12] Updates --- .../src/banner/specs/README.md | 117 +++++++++--------- 1 file changed, 59 insertions(+), 58 deletions(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index 1f005c7c69..4b2d40a530 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -12,15 +12,15 @@ The banner is a component used to display a persistent notification to a user. ### Non-goals -- Arbitrary HTML content -- A container component that would enforce design constraints on multiple banners displayed together -- Limiting length of displayed text and/or truncating text with ellipsis +- Arbitrary HTML content +- A container component that would enforce design constraints on multiple banners displayed together +- Limiting 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 +- 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 @@ -42,24 +42,23 @@ When the user presses the close button, we will hide the banner (`display:none`) ### 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. - - `text` - the message text - - `prevent-dismiss` - set to hide the close button (attr name taken from Nimble dialog) - - `severity` - one of `error`, `warning`, `info`, or undefined (default) - - `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. -- *Slots* - - `title` - for the title/header text - - (default) - for the primary message text - - `action` - for the action button/link -- *CSS Classes and CSS Custom Properties that affect the component* +_The key elements of the component's public API surface:_ + +- _Component Name_: `nimble-banner` +- _Props/Attrs_: + - `open` - whether the banner is visible or not + - `prevent-dismiss` - set to hide the close button (attr name taken from Nimble dialog) + - `severity` - one of `error`, `warning`, `info`, or undefined (default) + - `close-button-title` - a localized title to give the close button (for a11y purposes) +- _Methods_ +- _Events_ + - `toggle` - fired when the banner is closed or opened. Event has `newState` and `oldState`. + - `action` - fired when the action button is activated (by mouse or keyboard). This is the intended way for clients to perform an action. +- _Slots_ + - `title` - for the title/header text + - (default) - for the primary message text + - `action` - for the action button/link +- _CSS Classes and CSS Custom Properties that affect the component_ We only formally support spans of text in the `title` and default slots, but we will not explicitly prevent other HTML from being slotted there. The `action` slot only expects `nimble-button` or `nimble-anchor`, and we will use the CSS `::slotted()` pseudo-element to remove all but those two element types. We will not explicitly prevent multiple elements from being slotted in the `action` slot, though we formally only support one. @@ -67,23 +66,23 @@ We only formally support spans of text in the `title` and default slots, but we ```html
- ${when(x => x.severity === 'error', html``)} - ${when(x => x.severity === 'warning', html``)} - ${when(x => x.severity === 'info', html``)} + ${when(x => x.severity === 'error', html``)} ${when(x => x.severity === 'warning', + html``)} ${when(x + => x.severity === 'info', html``)}
- - + +
- -
- ${when(x => !x.preventDismiss), html` - - - ` - )} -
+ +
+ ${when(x => !x.preventDismiss), html` + + ` )} +
``` @@ -100,15 +99,16 @@ Blazor integration for the `nimble-banner` will be provided. 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`. +- 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`. --- @@ -120,19 +120,19 @@ N/A ### Accessibility -*Consider the accessibility of the component, including:* +_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 +- _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 @@ -163,4 +163,5 @@ N/A Storybook stories will be created. --- -## Open Issues \ No newline at end of file + +## Open Issues From 05bcdb59cfd7174f4b72f595647166058509721d Mon Sep 17 00:00:00 2001 From: m-akinc <7282195+m-akinc@users.noreply.github.com> Date: Fri, 27 Jan 2023 10:29:13 -0600 Subject: [PATCH 06/12] Update packages/nimble-components/src/banner/specs/README.md Co-authored-by: mollykreis <20542556+mollykreis@users.noreply.github.com> --- packages/nimble-components/src/banner/specs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index 4b2d40a530..b1bb93194c 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -20,7 +20,7 @@ The banner is a component used to display a persistent notification to a user. - Optionally dismissable - Optional link or button (only 1) to perform an action/navigation -- Distinct designs for banners of type Error, Warning, Info, or Neutral +- Distinct designs for banners of severity Error, Warning, Info, or Default ### Risks and Challenges From 53aa1d74317a7eee0d8ed1e37ec93af3c5091c6a Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Fri, 27 Jan 2023 10:58:55 -0600 Subject: [PATCH 07/12] Updates --- .../src/banner/specs/README.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index b1bb93194c..89a0d378d3 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -49,11 +49,11 @@ _The key elements of the component's public API surface:_ - `open` - whether the banner is visible or not - `prevent-dismiss` - set to hide the close button (attr name taken from Nimble dialog) - `severity` - one of `error`, `warning`, `info`, or undefined (default) + - `title-hidden` - set to hide the title text, which should always be provided for a11y reasons - `close-button-title` - a localized title to give the close button (for a11y purposes) - _Methods_ - _Events_ - `toggle` - fired when the banner is closed or opened. Event has `newState` and `oldState`. - - `action` - fired when the action button is activated (by mouse or keyboard). This is the intended way for clients to perform an action. - _Slots_ - `title` - for the title/header text - (default) - for the primary message text @@ -64,24 +64,28 @@ We only formally support spans of text in the `title` and default slots, but we ### Anatomy + ```html
- ${when(x => x.severity === 'error', html``)} ${when(x => x.severity === 'warning', - html``)} ${when(x - => x.severity === 'info', html``)} + ${when(x => x.severity === 'error', html` + `)} + ${when(x => x.severity === 'warning', html` + `)} + ${when(x => x.severity === 'info', html` + `)}
- + ${when(x => !x.titleHidden, html` + )}
${when(x => !x.preventDismiss), html` - - ` )} + + + ` )}
``` From b0b5ce582514f12f969b962ec797ffff81ebbd7b Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Fri, 27 Jan 2023 13:13:37 -0600 Subject: [PATCH 08/12] Updates --- .../src/banner/specs/README.md | 36 ++++++++++++++++--- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index 89a0d378d3..16704ce392 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -38,7 +38,7 @@ The banner is a standalone component that spans the width of its containing elem 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 (`display:none`) and fire a `close` event. +When the user presses the dismiss button, we will hide the banner (`display:none`) and fire a `close` event. ### API @@ -47,10 +47,10 @@ _The key elements of the component's public API surface:_ - _Component Name_: `nimble-banner` - _Props/Attrs_: - `open` - whether the banner is visible or not - - `prevent-dismiss` - set to hide the close button (attr name taken from Nimble dialog) + - `prevent-dismiss` - set to hide the dismiss button (attr name taken from Nimble dialog) - `severity` - one of `error`, `warning`, `info`, or undefined (default) - `title-hidden` - set to hide the title text, which should always be provided for a11y reasons - - `close-button-title` - a localized title to give the close button (for a11y purposes) + - `dismiss-button-label` - a localized label to give the dismiss button (for a11y purposes) - _Methods_ - _Events_ - `toggle` - fired when the banner is closed or opened. Event has `newState` and `oldState`. @@ -60,7 +60,33 @@ _The key elements of the component's public API surface:_ - `action` - for the action button/link - _CSS Classes and CSS Custom Properties that affect the component_ -We only formally support spans of text in the `title` and default slots, but we will not explicitly prevent other HTML from being slotted there. The `action` slot only expects `nimble-button` or `nimble-anchor`, and we will use the CSS `::slotted()` pseudo-element to remove all but those two element types. We will not explicitly prevent multiple elements from being slotted in the `action` slot, though we formally only support one. +We only formally support spans of text in the `title` and default slots, but we will not explicitly prevent other HTML from being slotted there. The `action` slot only supports a single `nimble-button` or `nimble-anchor`, but again, we will not do anything to enforce this. + +### Examples + +```html + + License Expiring + Your license will expire at the end of the month. To renew, go to + ni.com/renew. + Renew my license + +``` + +```html + + Authentication Failed + Could not authenticate. Please re-enter your credentials from Settings. + Open Settings + +``` + +```html + + Demo mode message + You are operating in demo mode. Some features will not be available. + +``` ### Anatomy @@ -127,7 +153,7 @@ N/A _Consider the accessibility of the component, including:_ - _Keyboard Navigation and Focus_ - - the action button/link and the close button will be focusable tab stops + - the action button/link and the dismiss button will be focusable tab stops - _Form Input_ - N/A - _Use with Assistive Technology_ From 416707648841c58a1900e75b1479a136b526a8ee Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Fri, 27 Jan 2023 13:14:13 -0600 Subject: [PATCH 09/12] Change files --- ...le-components-4335e721-003a-45f5-82fb-8602f6bc2932.json | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 change/@ni-nimble-components-4335e721-003a-45f5-82fb-8602f6bc2932.json diff --git a/change/@ni-nimble-components-4335e721-003a-45f5-82fb-8602f6bc2932.json b/change/@ni-nimble-components-4335e721-003a-45f5-82fb-8602f6bc2932.json new file mode 100644 index 0000000000..103441e022 --- /dev/null +++ b/change/@ni-nimble-components-4335e721-003a-45f5-82fb-8602f6bc2932.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "Banner spec", + "packageName": "@ni/nimble-components", + "email": "7282195+m-akinc@users.noreply.github.com", + "dependentChangeType": "none" +} From 74cab77cfff03106636e654f0cd83164797f0796 Mon Sep 17 00:00:00 2001 From: Mert Akinc <7282195+m-akinc@users.noreply.github.com> Date: Fri, 27 Jan 2023 14:07:46 -0600 Subject: [PATCH 10/12] Change reference to wrong event name --- packages/nimble-components/src/banner/specs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index 16704ce392..2ea79c66d6 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -38,7 +38,7 @@ The banner is a standalone component that spans the width of its containing elem 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 dismiss button, we will hide the banner (`display:none`) and fire a `close` event. +When the user presses the dismiss button, we will hide the banner (`display:none`) and fire a `toggle` event. ### API From e7f0a54208f830ca225418c373b08e3df8e8ee6d Mon Sep 17 00:00:00 2001 From: m-akinc <7282195+m-akinc@users.noreply.github.com> Date: Tue, 7 Feb 2023 17:50:18 +0000 Subject: [PATCH 11/12] Update packages/nimble-components/src/banner/specs/README.md Co-authored-by: mollykreis <20542556+mollykreis@users.noreply.github.com> --- packages/nimble-components/src/banner/specs/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index 2ea79c66d6..c868cee936 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -111,6 +111,7 @@ We only formally support spans of text in the `title` and default slots, but we ${when(x => !x.preventDismiss), html` + ${x => x.dismissButtonLabel} ` )}
From 3167444c844c0cc01fd57e07694723a3104b619d Mon Sep 17 00:00:00 2001 From: m-akinc <7282195+m-akinc@users.noreply.github.com> Date: Tue, 7 Feb 2023 11:50:29 -0600 Subject: [PATCH 12/12] Update packages/nimble-components/src/banner/specs/README.md Co-authored-by: mollykreis <20542556+mollykreis@users.noreply.github.com> --- packages/nimble-components/src/banner/specs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/nimble-components/src/banner/specs/README.md b/packages/nimble-components/src/banner/specs/README.md index c868cee936..6449028bce 100644 --- a/packages/nimble-components/src/banner/specs/README.md +++ b/packages/nimble-components/src/banner/specs/README.md @@ -102,7 +102,7 @@ We only formally support spans of text in the `title` and default slots, but we
${when(x => !x.titleHidden, html` - )} + `)}