Merge pull request #1812 from Kajabi/docs/update-loader-component-docs

docs(loader): update the react loader documentation
Kajabi · Oct 24, 2023 · b859c9e · b859c9e
2 parents 0b3a6dc + b46276a
commit b859c9e
Show file tree

Hide file tree

Showing 5 changed files with 196 additions and 67 deletions.
diff --git a/docs/app/views/examples/components/loader/_preview.html.erb b/docs/app/views/examples/components/loader/_preview.html.erb
@@ -1,29 +1,48 @@
-<h2 class="<%= SageClassnames::TYPE::HEADING_6 %>">Without text</h2>
-<div class="sage-row">
-  <div class="sage-col--md-6 example__block--lg">
+<h2>Variants</h2>
+
+<h3>Bar</h3>
+<%= sage_component SageGridRow, {} do %>
+  <%= sage_component SageGridCol, { size: 12, css_classes: "example__block--lg" } do %>
     <%= sage_component SageLoader, {
-      type: "spinner"
+      type: "bar"
     } %>
-  </div>
-  <div class="sage-col--md-6 example__block--lg">
-    <%= sage_component SageLoader, {
-      type: "success"
-    } %>
-  </div>
-</div>
-<hr>
-<h2 class="<%= SageClassnames::TYPE::HEADING_6 %>">With text</h2>
-<div class="sage-row">
-  <div class="sage-col--md-6 example__block--lg">
+  <% end %>
+<% end %>
+
+<%= sage_component SageDivider, {} %>
+
+<h3>Spinner</h3>
+<%= sage_component SageGridRow, {} do %>
+  <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %>
+    <h2 class="<%= SageClassnames::TYPE::HEADING_6 %>">With text</h2>
     <%= sage_component SageLoader, {
       type: "spinner",
       text: true
     } %>
-  </div>
-  <div class="sage-col--md-6 example__block--lg">
+  <% end %>
+  <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %>
+    <h2 class="<%= SageClassnames::TYPE::HEADING_6 %>">Without text</h2>
+    <%= sage_component SageLoader, {
+      type: "spinner"
+    } %>
+  <% end %>
+<% end %>
+
+<%= sage_component SageDivider, {} %>
+
+<h3>Success</h3>
+<%= sage_component SageGridRow, {} do %>
+  <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %>
+    <h2 class="<%= SageClassnames::TYPE::HEADING_6 %>">With text</h2>
     <%= sage_component SageLoader, {
       type: "success",
       text: true
     } %>
-  </div>
-</div>
+  <% end %>
+  <%= sage_component SageGridCol, { size: 6, css_classes: "example__block--lg" } do %>
+    <h2 class="<%= SageClassnames::TYPE::HEADING_6 %>">Without text</h2>
+    <%= 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
@@ -1,12 +1,19 @@
 <tr>
-  <td><%= md('`type`') %><%= sage_component SageBadge, { color: "published", value: "required" } %></td>
-  <td><%= md('Determines which loader will be used; `spinner` or `success`') %></td>
-  <td><%= md('String') %></td>
-  <td><%= md('`nil`') %></td>
+  <td><%= md('`fill`') %>
+  <td><%= md('If true, will fill the space within the container.') %></td>
+  <td><%= md('Boolean') %></td>
+  <td><%= md('`false`') %></td>
 </tr>
 <tr>
   <td><%= md('`text`') %></td>
   <td><%= md('Includes text that aligns with the loader.') %></td>
   <td><%= md('Boolean') %></td>
+  <td><%= md('`false`') %></td>
+</tr>
+<tr>
+  <td><%= md('`type`') %><%= sage_component SageBadge, { color: "published", value: "required" } %></td>
+  <td><%= md('Determines which loader will be used; `bar`, `spinner` or `success`') %></td>
+  <td><%= md('String') %></td>
   <td><%= md('`nil`') %></td>
 </tr>
+
diff --git 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
diff --git a/packages/sage-react/lib/Loader/Loader.story.mdx 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';
+
+<Meta
+  title="Sage/Loader"
+  component={Loader}
+   argTypes={{
+    type: {
+      name: 'Type',
+      description: 'The type of Loader to be rendered',
+      options: Object.values(Loader.TYPES)
+    }
+  }}
+  args={{
+    loading: true,
+  }}
+/>
+
+# 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
+
+<ArgsTable story="Default" />
+
+### 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`
+
+<Canvas>
+  <Story name="Default">
+    <Loader loading={true} />
+  </Story>
+</Canvas>
+
+### 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.
+
+<Canvas>
+ <Story name="Bar">
+  <Loader loading={true} type={Loader.TYPES.BAR} />
+ </Story>
+</Canvas>
+
+### 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.
+
+<Canvas>
+ <Story name="Spinner">
+  <Loader loading={true} type={Loader.TYPES.SPINNER} />
+ </Story>
+</Canvas>
+
+### Success
+This should be used to notify the user that the process/request has been completed succesfully.
+
+<Canvas>
+ <Story name="Success">
+  <Loader loading={true} type={Loader.TYPES.SUCCESS} />
+ </Story>
+</Canvas>
+
+### Typing
+This loading indicator is good when you want to provide feedback to the user that they are typing.
+
+<Canvas>
+ <Story name="Typing">
+  <Loader loading={true} type={Loader.TYPES.TYPING} />
+ </Story>
+</Canvas>
+
+## Additional Properties
+
+### Fill Space (deprecated)
+<Canvas>
+  <Story name="Fill Space - Deprecated">
+    <div>
+      <Loader loading={true} fillSpace={true} />
+    </div>
+  </Story>
+</Canvas>
+
+### Hide when Done
+Setting this property will hide the loader when the process/request has been completed.
+<Canvas>
+  <Story name="Hide When Done - Deprecated">
+    <Loader hideWhenDone={true} />
+  </Story>
+</Canvas>
+
+### Label
+Allows you to provide custom text to the Spinner loader.
+
+<Canvas>
+  <Story name="Label">
+    <Loader loading={true} label="My loading label...." type={Loader.TYPES.SPINNER} />
+  </Story>
+</Canvas>