diff --git a/change/@ni-nimble-components-cb67d3ce-526f-411d-ba8d-60cea6651936.json b/change/@ni-nimble-components-cb67d3ce-526f-411d-ba8d-60cea6651936.json new file mode 100644 index 0000000000..b8e99cb95d --- /dev/null +++ b/change/@ni-nimble-components-cb67d3ce-526f-411d-ba8d-60cea6651936.json @@ -0,0 +1,7 @@ +{ + "type": "none", + "comment": "Add spec document for nimble-spinner.", + "packageName": "@ni/nimble-components", + "email": "20709258+msmithNI@users.noreply.github.com", + "dependentChangeType": "none" +} diff --git a/packages/nimble-components/src/spinner/specs/BlazorWebConfigSpinner.gif b/packages/nimble-components/src/spinner/specs/BlazorWebConfigSpinner.gif new file mode 100644 index 0000000000..d5c3d2ef08 Binary files /dev/null and b/packages/nimble-components/src/spinner/specs/BlazorWebConfigSpinner.gif differ diff --git a/packages/nimble-components/src/spinner/specs/NewSpinnerDesign.gif b/packages/nimble-components/src/spinner/specs/NewSpinnerDesign.gif new file mode 100644 index 0000000000..7aee415301 Binary files /dev/null and b/packages/nimble-components/src/spinner/specs/NewSpinnerDesign.gif differ diff --git a/packages/nimble-components/src/spinner/specs/README.md b/packages/nimble-components/src/spinner/specs/README.md new file mode 100644 index 0000000000..807a147e2b --- /dev/null +++ b/packages/nimble-components/src/spinner/specs/README.md @@ -0,0 +1,145 @@ +# Nimble Spinner + +## Overview + +Spinner component (`nimble-spinner`): Indeterminate progress indicator / loading indicator. Meant to be temporarily used in a region of a web page until that region's contents have loaded, or to represent an ongoing operation that doesn't have a known/ determinate duration. + +### Background + +[Nimble spinner: #346](https://github.com/ni/nimble/issues/346) +[Nimble spinner design: #822](https://github.com/ni/nimble/issues/822) +[Visual Design spec - Adobe XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/dece308f-79e7-48ec-ab41-011f3376b49b/) + +[Follow-up issue about PowerGreen/custom color variants: #916](https://github.com/ni/nimble/issues/916) + +### Non-goals + +Ability to show determinate progress: + +- The current visual design for the spinner is distinct/different from an indeterminate radial progress bar +- We don't currently have visual designs for a linear or radial progress bar with determinate progress +- If/when we want progress bar components in the future, at that point we'll probably create new Nimble components which extend the corresponding FAST components: + - `nimble-progress` or `nimble-linear-progress`, deriving from `fast-progress`, for a linear progress bar; and + - `nimble-progress-ring` or `nimble-radial-progress`, deriving from `fast-progress-ring`, for a radial progress bar + +### Features + +- Show indeterminate progress with an animation + - Cannot be paused - assumption is that component will be added to/ removed from the page as needed +- Supports 3 sizes: `small` (16x16), `medium` (32x32) (default), `large` (64x64) + - Component will scale to other sizes if needed (if width/height styles are set on it directly), for advanced use cases + +### Risks and Challenges + +None + +### Prior Art/Examples + +SystemLink Enterprise uses a spinner based on the Material `mat-spinner`: +![SystemLink Material spinner](SlMatSpinner.gif) + +A variant of this spinner design is already implemented in the Web Config tool written in Blazor: +![Blazor Web Config spinner](BlazorWebConfigSpinner.gif) + +## Design + +The `nimble-spinner` is an animating indicator that can be placed in a particular region of a page to represent loading progress, or an ongoing operation, of an indeterminate / unknown duration. + +### API + +Component Name: `nimble-spinner` + +Properties/Attributes: + +- `size` + - String attribute controlling size of the component + - Backed by an enum `SpinnerSize` with values `small` (16x16), `medium` (32x32), `large` (64x64) + - If omitted, the default is `medium` (32x32) + - If omitted, custom `width` and `height` styles can be set on the `nimble-spinner` and the animating elements will scale to that size. In this case, consumer should follow up with Design to doublecheck the padding needed. + +Methods, Events, CSS Classes, CSS Custom Properties: None + +### Anatomy + +Contains 2 `div` elements that are animated via CSS animations. + +Slot Names, Host Classes, Slotted Content/ Slotted Classes, CSS Parts: None + +### Angular integration + +Directive `NimbleSpinnerDirective` targeting selector `nimble-spinner`, with bindings for `size`. + +### Blazor integration + +Standard Blazor implementation (`NimbleSpinner` deriving from `ComponentBase`), with bindings for `size`. + +### Visual Appearance + +[Visual Design spec - Adobe XD](https://xd.adobe.com/view/33ffad4a-eb2c-4241-b8c5-ebfff1faf6f6-66ac/screen/dece308f-79e7-48ec-ab41-011f3376b49b/) + +![New spinner design](NewSpinnerDesign.gif) +**Note:** 'Color UI Alt.' appearance is unsupported for the initial implementation, see the _Potential Future Enhancements_ section. + +When `prefers-reduced-motion` is enabled, a simplified version will be used: +![Spinner, Prefers Reduced Motion](SpinnerPrefersReducedMotion.gif) + +## Implementation + +Component implementation will derive from the FAST `FoundationElement`. + +**Alternatives Considered:** We could derive from `fast-progress-ring` (radial progress indicator, which supports an indeterminate progress display), however then our component API would also pick up the `min`/`max`/`value` properties for determinate progress (and `paused` to pause the indicator), which we don't plan on supporting at this time. Additionally, the visual appearance of our spinner will be a little different from a radial progress bar, and we still may end up supporting a standard radial progress bar in the future. +For reference, the FAST spec for `progress` / `progress-ring` is [here](https://github.com/microsoft/fast/blob/802443ffb2b19a078f9b48f62e6d1a35e3276fb5/packages/web-components/fast-foundation/src/progress/README.md). + +### States + +Only one component state: visible and animating. Pausing not supported; spinner is expected to be added/removed from the DOM as needed. + +### Accessibility + +No keyboard states / form integration. + +ARIA: We plan to use the [`progressbar role`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role) without setting `aria-valuemin` / `aria-valuemax` / `aria-valuenow` (representing indeterminate). +This matches the behavior of an indeterminate FAST progress ring (in which case min/max/value are unset) - see the [FAST template here](https://github.com/microsoft/fast/blob/802443ffb2b19a078f9b48f62e6d1a35e3276fb5/packages/web-components/fast-foundation/src/progress-ring/progress-ring.template.ts#L17). + +`prefers-reduced-motion`: A simplified spinner indicator will be shown when this is enabled, see the Visual Appearance section. + +### Globalization + +N/A. + +RTL: No special handling / no changes to the spinner animation. Linear indeterminate progress animations are sometimes reversed for RTL, but circular/clockwise ones are usually not (see [Material Design v2, Mirroring Elements](https://m2.material.io/design/usability/bidirectionality.html#mirroring-elements) > _When Not To Mirror_, for one example). + +### Security + +N/A + +### Performance + +N/A + +### Dependencies + +None + +### Test Plan + +Standard tests planned. +[Chromatic is supposed to handle pausing CSS animations by default](https://www.chromatic.com/docs/animations), however we should verify that by ensuring the snapshots of the spinner show the same state across 2 Chromatic builds. + +### Tooling + +N/A + +### Documentation + +N/A - Standard updates of the component table in the README, and in Storybook. + +## Potential Future Enhancements + +- Do we need to support the "Color UI Alt" (PowerGreen) spinner appearance, and do apps/consumers need a way to override the spinner color? + - Original plan for supporting that appearance: adding a `theme-variant` attribute: + - default (undefined): Standard appearance (light/dark/color themes) + - `prominent`: Alternate appearance/color, for the color theme only ('Color UI Alt.' from XD design) + - Backed by enum `SpinnerThemeVariant` + - We could also follow the patterns from our icons (create a token `spinner-color` that can be overridden) + - **Decision**: We will omit the Color UI Alt appearance for our initial implementation. Followup questions that need to be answered are captured in [Issue #916](https://github.com/ni/nimble/issues/916). diff --git a/packages/nimble-components/src/spinner/specs/SlMatSpinner.gif b/packages/nimble-components/src/spinner/specs/SlMatSpinner.gif new file mode 100644 index 0000000000..1af4b6b700 Binary files /dev/null and b/packages/nimble-components/src/spinner/specs/SlMatSpinner.gif differ diff --git a/packages/nimble-components/src/spinner/specs/SpinnerPrefersReducedMotion.gif b/packages/nimble-components/src/spinner/specs/SpinnerPrefersReducedMotion.gif new file mode 100644 index 0000000000..cccccbd617 Binary files /dev/null and b/packages/nimble-components/src/spinner/specs/SpinnerPrefersReducedMotion.gif differ