From 18fa9734c7c1c44f120ba92b5ee34518207cddb9 Mon Sep 17 00:00:00 2001 From: Julian Skinner Date: Wed, 11 Oct 2023 16:02:44 -0600 Subject: [PATCH 1/2] docs(loader): update the react loader documentation --- packages/sage-react/lib/Loader/Loader.jsx | 22 ++- .../sage-react/lib/Loader/Loader.story.jsx | 42 ------ .../sage-react/lib/Loader/Loader.story.mdx | 127 ++++++++++++++++++ 3 files changed, 147 insertions(+), 44 deletions(-) delete mode 100644 packages/sage-react/lib/Loader/Loader.story.jsx create mode 100644 packages/sage-react/lib/Loader/Loader.story.mdx diff --git a/packages/sage-react/lib/Loader/Loader.jsx b/packages/sage-react/lib/Loader/Loader.jsx index de5635745c..115193c292 100644 --- a/packages/sage-react/lib/Loader/Loader.jsx +++ b/packages/sage-react/lib/Loader/Loader.jsx @@ -89,14 +89,32 @@ Loader.defaultProps = { fillSpace: false, label: 'Loading...', hideWhenDone: true, - type: LOADER_TYPES.SPINNER, + type: Loader.TYPES.SPINNER, }; Loader.propTypes = { + /** + * The name of the class you want to apply to the loader. + */ className: PropTypes.string, + /** + * If true, will fill the space within the container. + */ fillSpace: PropTypes.bool, + /** + * If true, will hide the loader when loading is false. + */ hideWhenDone: PropTypes.bool, + /** + * The text that aligns with the loader. + */ label: PropTypes.string, + /** + * If true, it will display the loader. + */ loading: PropTypes.bool.isRequired, - type: PropTypes.oneOf(Object.values(LOADER_TYPES)), + /** + * The type of Loader to be rendered + */ + type: PropTypes.oneOf(Object.values(Loader.TYPES)), }; diff --git a/packages/sage-react/lib/Loader/Loader.story.jsx b/packages/sage-react/lib/Loader/Loader.story.jsx deleted file mode 100644 index 10192aca79..0000000000 --- a/packages/sage-react/lib/Loader/Loader.story.jsx +++ /dev/null @@ -1,42 +0,0 @@ -import React from 'react'; -import { selectArgs } from '../story-support/helpers'; -import { Card } from '../Card'; -import { Grid } from '../Grid'; -import { Loader } from './Loader'; - -export default { - title: 'Sage/Loader', - component: Loader, - // displays description on Docs tab - parameters: { - docs: { - description: { - component: 'Stylized loading animations for use with components.' - }, - }, - }, - argTypes: { - ...selectArgs({ - type: Loader.TYPES - }), - }, - args: { - fillSpace: true, - loading: true, - type: Loader.TYPES.BAR - } -}; -const Template = (args) => ; - -export const Default = Template.bind({}); -Default.decorators = [ - (Story) => ( - <> - - - {Story()} - - - - ) -]; diff --git a/packages/sage-react/lib/Loader/Loader.story.mdx b/packages/sage-react/lib/Loader/Loader.story.mdx new file mode 100644 index 0000000000..116643ec25 --- /dev/null +++ b/packages/sage-react/lib/Loader/Loader.story.mdx @@ -0,0 +1,127 @@ +import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs'; +import { Loader } from './Loader'; + + + +# Loader + +Animated UI elements indicating that a page, section, or action is loading. + +## Usage Guidelines + +- Communicate that the system is working on a request. + +### When to use + +- Communicate to the user that something is loading. +- Any action that cannot be performed instantly and will require a short time to process. + +## Accessibility + +We achieve accessibility by leveraging the ARIA attributes `aria-live` and `aria-busy`. Each of these provide information to +screen readers and assitive tech. + +- ARIA Busy indicates that an element is currently in a state of being updated or undergoing changes. +- ARIA Live at its core defines how dynamic content changes are announced to the user. We use the `Polite` option, which informs the user +without interrupting the user. + +## Properties + + + +### Types of Loaders +- Bar +- Spinner +- Spinner in Button +- Success +- Typing + +## Variants + +### Default +When using the component in its default state, it will use the default type of `SPINNER` + + + + + + + +### Bar +The continuous progress bar is used when the content and the indefinable loading progress of the system +are to be displayed in the view at the same time. + + + + + + + +### Spinner +The continuous spinner is used when loading progress cannot be determined. They indicate to the user +with continuous movement that the system is still processing. + + + + + + + +### Success +This should be used to notify the user that the process/request has been completed succesfully. + + + + + + + +### Typing +This loading indicator is good when you want to provide feedback to the user that they are typing. + + + + + + + +## Additional Properties + +### Fill Space (deprecated) + + +
+ +
+ + + +### Hide when Done +Setting this property will hide the loader when the process/request has been completed. + + + + + + +### Label +Allows you to provide custom text to the Spinner loader. + + + + + + From b46276a4756073e6dba653c61e662880e033239b Mon Sep 17 00:00:00 2001 From: Julian Skinner Date: Tue, 17 Oct 2023 16:19:14 -0500 Subject: [PATCH 2/2] docs(loader): add additional details for Rails Loader component --- .../components/loader/_preview.html.erb | 57 ++++++++++++------- .../components/loader/_props.html.erb | 15 +++-- 2 files changed, 49 insertions(+), 23 deletions(-) diff --git a/docs/app/views/examples/components/loader/_preview.html.erb b/docs/app/views/examples/components/loader/_preview.html.erb index 8a089ef240..b1eec7fcc9 100644 --- a/docs/app/views/examples/components/loader/_preview.html.erb +++ b/docs/app/views/examples/components/loader/_preview.html.erb @@ -1,29 +1,48 @@ -

Without text

-
-
+

Variants

+ +

Bar

+<%= sage_component SageGridRow, {} do %> + <%= sage_component SageGridCol, { size: 12, css_classes: "example__block--lg" } do %> <%= sage_component SageLoader, { - type: "spinner" + type: "bar" } %> -
-
- <%= sage_component SageLoader, { - type: "success" - } %> -
-
-
-

With text

-
-
+ <% end %> +<% end %> + +<%= sage_component SageDivider, {} %> + +

Spinner

+<%= sage_component SageGridRow, {} do %> + <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %> +

With text

<%= sage_component SageLoader, { type: "spinner", text: true } %> -
-
+ <% end %> + <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %> +

Without text

+ <%= sage_component SageLoader, { + type: "spinner" + } %> + <% end %> +<% end %> + +<%= sage_component SageDivider, {} %> + +

Success

+<%= sage_component SageGridRow, {} do %> + <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %> +

With text

<%= sage_component SageLoader, { type: "success", text: true } %> -
-
+ <% end %> + <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %> +

Without text

+ <%= sage_component SageLoader, { + type: "success" + } %> + <% end %> +<% end %> diff --git a/docs/app/views/examples/components/loader/_props.html.erb b/docs/app/views/examples/components/loader/_props.html.erb index 141ddb9128..b40d09355a 100644 --- a/docs/app/views/examples/components/loader/_props.html.erb +++ b/docs/app/views/examples/components/loader/_props.html.erb @@ -1,12 +1,19 @@ - <%= md('`type`') %><%= sage_component SageBadge, { color: "published", value: "required" } %> - <%= md('Determines which loader will be used; `spinner` or `success`') %> - <%= md('String') %> - <%= md('`nil`') %> + <%= md('`fill`') %> + <%= md('If true, will fill the space within the container.') %> + <%= md('Boolean') %> + <%= md('`false`') %> <%= md('`text`') %> <%= md('Includes text that aligns with the loader.') %> <%= md('Boolean') %> + <%= md('`false`') %> + + + <%= md('`type`') %><%= sage_component SageBadge, { color: "published", value: "required" } %> + <%= md('Determines which loader will be used; `bar`, `spinner` or `success`') %> + <%= md('String') %> <%= md('`nil`') %> +