docs(Loader): add JSDoc comments, enhance story (#930)

Author: Lukas742

packages/main/src/components/Loader/Loader.stories.mdx

@@ -0,0 +1,128 @@
+import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
+import { Loader } from '@ui5/webcomponents-react/lib/Loader';
+import { LoaderType } from '@ui5/webcomponents-react/lib/LoaderType';
+import { Card } from '@ui5/webcomponents-react/lib/Card';
+import { Text } from '@ui5/webcomponents-react/lib/Text';
+import { Icon } from '@ui5/webcomponents-react/lib/Icon';
+import { FlexBox } from '@ui5/webcomponents-react/lib/FlexBox';
+import { FlexBoxDirection } from '@ui5/webcomponents-react/lib/FlexBoxDirection';
+import { createSelectArgTypes } from '@shared/stories/createSelectArgTypes';
+import { DocsHeader } from '@shared/stories/DocsHeader';
+import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
+import { spacing } from '@ui5/webcomponents-react-base';
+import '@ui5/webcomponents-icons/dist/icons/activate.js';
+import { useEffect, useRef, useState } from 'react';
+
+<Meta
+  title="Components / Loader"
+  component={Loader}
+  argTypes={{
+    ...createSelectArgTypes({ type: LoaderType }),
+    ...DocsCommonProps
+  }}
+  args={{
+    type: LoaderType.Indeterminate,
+    progress: '60%',
+    style: {},
+    className: '',
+    tooltip: '',
+    slot: '',
+    ref: null
+  }}
+/>
+
+<DocsHeader />
+
+<Canvas>
+  <Story name="Default">
+    {(args) => {
+      return <Loader {...args} />;
+    }}
+  </Story>
+</Canvas>
+
+<ArgsTable story="." />
+
+<br />
+
+# Stories
+
+<br />
+
+## Card with Loader
+
+<Canvas>
+  <Story name="with Card">
+    {(args) => {
+      const initialText =
+        'This is a text that will be updated 5 seconds after the header is clicked. The text will be visible until the new text has been fetched. To let the user know that the text is updating, the Loader will be displayed.';
+      const [text, setText] = useState(initialText);
+      const [loading, setLoading] = useState(false);
+      const counter = useRef(0);
+      const onHeaderClick = () => {
+        setLoading(true);
+      };
+      useEffect(() => {
+        if (loading) {
+          setTimeout(() => {
+            if (counter.current < 10) {
+              setText((prev) => (prev === initialText ? 'Updated (⌐■_■)' : initialText));
+            } else {
+              setText('You really must be bored ಠ_ಠ');
+            }
+            counter.current++;
+            setLoading(false);
+          }, 5000);
+        }
+      }, [loading]);
+      return (
+        <Card
+          avatar={<Icon name="activate" />}
+          heading="Click the header to update the text below."
+          headerInteractive
+          style={{ width: '400px' }}
+          onHeaderClick={onHeaderClick}
+        >
+          <FlexBox direction={FlexBoxDirection.Column}>
+            {loading && <Loader {...args} />}
+            <Text style={spacing.sapUiContentPadding}>{text}</Text>
+          </FlexBox>
+        </Card>
+      );
+    }}
+  </Story>
+</Canvas>
+
+```jsx
+const LoaderComponent = () => {
+  const initialText =
+    'This is a text that will be updated 5 seconds after the header is clicked. The text will be visible until the new text has been fetched. To let the user know that the text is updating, the Loader will be displayed.';
+  const [text, setText] = useState(initialText);
+  const [loading, setLoading] = useState(false);
+  const onHeaderClick = () => {
+    setLoading(true);
+  };
+  useEffect(() => {
+    if (loading) {
+      setTimeout(() => {
+        setText((prev) => (prev === initialText ? 'Updated (⌐■_■)' : initialText));
+        setLoading(false);
+      }, 5000);
+    }
+  }, [loading]);
+  return (
+    <Card
+      avatar={<Icon name="activate" />}
+      heading="Click the header to update the text below."
+      headerInteractive
+      style={{ width: '400px' }}
+      onHeaderClick={onHeaderClick}
+    >
+      <FlexBox direction={FlexBoxDirection.Column}>
+        {loading && <Loader />}
+        <Text style={spacing.sapUiContentPadding}>{text}</Text>
+      </FlexBox>
+    </Card>
+  );
+};
+```

packages/main/src/components/Loader/demo.stories.tsx

@@ -9,16 +9,27 @@ import { CommonProps } from '../../interfaces/CommonProps';
 import { styles } from './Loader.jss';
 
 export interface LoaderProps extends CommonProps {
-  /*
+  /**
    * Delay in ms until the Loader will be displayed
    */
   delay?: number;
+  /**
+   * Defines the type of the `Loader`.
+   * __Note:__ If the process completion rate can be detected the `Determinate` type should be used.
+   */
   type?: LoaderType;
+  /**
+   * Defines the progress of the Loader Bar. <br />
+   * __Note:__ This prop has no effect if used with type `Indeterminate`.
+   */
   progress?: CSSProperties['width'];
 }
 
 const useStyles = createComponentStyles(styles, { name: 'Loader' });
-
+/**
+ * The `Loader` signals that an operation is currently being executed. It uses as little space as possible to allow the user to interact with the UI.<br />
+ * It can be used to signal a data update on an already existing dataset, or where an expansion will happen.
+ */
 const Loader: FC<LoaderProps> = forwardRef((props: LoaderProps, ref: RefObject<HTMLDivElement>) => {
   const { className, type, progress, tooltip, slot, style, delay } = props;
   const classes = useStyles(props);