Vika-Loader

topics/ui/controls/loader.md

@@ -12,17 +12,13 @@
 
 </tldr>
 
-A loader informs users about performing a lengthy operation.
+A loader indicates that an operation is in progress. It consists of a loader icon with a process name or a loader icon alone.
 
-![](loader.png){width=330}
+![Loader anatomy](anatomy.png){width=706}
 
-## When to use
-
-Follow the rules for [progress indicators](progress_indicators.md).
 
-## How to use
+<chapter level="3" title="Implementation" collapsible="true" default-state="collapsed">
 
-The loader form and sizes are the same in all themes. Use the default 16&times;16 loader in all cases.
 <tabs group="languages">
 <tab title="Kotlin" group-key="kotlin">
 
@@ -33,7 +29,6 @@ JLabel(
     SwingConstants.LEFT
 )
 ```
-
 </tab>
 <tab title="Java" group-key="java">
 
@@ -44,53 +39,84 @@ new JLabel(
     SwingConstants.LEFT
 );
 ```
-
 </tab>
 </tabs>
+</chapter>
+
+## When to use
+
+### Field, dropdown, or combobox
+If content in a control takes time to load, place a loader on the right side inside the field.
+
+![Using in field, dropdown, or combobox](02.png){width=706}
+
+### Tree or list
+
+If tree nodes load independently and their individual states matter, display loaders instead of node icons.
+
+![Using in tree or list](03.png){width=706}
+
+If icons can’t be replaced, show a process name after a node label.
+
+![Process name after a node label](04.png){width=706}
+
+If a loader applies to the entire content below, use the [Inline progress](progress_bar.md#inline-progress) instead.
+
+### Empty state
+
+Show a loader while content is being loaded.
+
+![Empty state](05.png){width=706}
+
+### Non-instant actions
+Display a loader near a button or link while an action is being performed.
+
+![Loader near a button](06.png){width=706}
+
+If an action appears as an icon on a toolbar, or space is limited, replace the action with a loader icon.
+
+![Loader instead of icon](07.png){width=706}
+
+## How to use
+
+### Process name and details
+A loader can show a process name and process details.
+
+#### Process name
+
+Always show the name of an operation being performed.
+Use the continuous form of the verb that describes the operation. Add an ellipsis at the end to indicate that the process is ongoing.
+
+![Process name](08.png){width=706}
+
+If there is no space for the process name, show it in a tooltip.
 
+![Process name in a tooltip](09.png){width=706}
 
+#### Process details
+Optionally show information about the current stage of an operation.
+Details make long-running tasks more predictable and manageable.
+<br>
+Show process details below the process name. The text should be concise and displayed on a single line.
 
-A loader may have a label if the process is long and the loader is shown in an empty area. In this case, use a [progress text](progress_text.md) as the label:
+![Process details](10.png){width=706}
 
-![](loader_with_progress_text.png){width=597}
+Details examples:
+* The current step: "Uploading file 3 of 10"
+* The current step: "Uploading file 3 of 10"
+* Remaining time or percentage completed
+* Round the remaining time to one of the following values: 1, 2, 3, 5, 10, 15, 20, or 30 seconds (or minutes). For example, if 7 minutes and 50 seconds remain, show "About 10 minutes left." If less than 5 seconds remain, show "About 5 seconds left."
 
-Remove the loader as soon as the process completes.
 
-## Placement
+#### Cancellation action
+If a process can be canceled, provide the Cancel action and place it on the right.
 
-<table style="none">
+![Cancellation action](11.png){width=706}
 
-<tr>
-    <td> Inside a field </td>
-    <td> <img src="placement_field.png" width="161"/> </td>
-</tr>
+#### Process completion
+Hide the loader as soon as the process completes.
 
-<tr>
-    <td colspan="2">
-        <code-block lang="java">
-            ExpandableTextField textField = new ExpandableTextField();
-            textField.addExtension(
-              Extension.create(new AnimatedIcon.Default(), null, null)
-            );
-        </code-block>
-    </td>
-</tr>
 
-<tr>
-    <td>In a corner</td>
-    <td> <img src="placement_corner.png" width="32" />
-    </td>
-</tr>
 
-<tr>
-    <td>  Next to an item </td>
-    <td> <img src="placement_item.png" width="55" /> </td>
-</tr>
 
-<tr>
-    <td> Before a progress text </td>
-    <td> <img src="placement_progress_text.png" width="110" />
-    </td>
-</tr>
 
-</table>