[FEATURE] UI: introduce new Progress\Bar component.

components/ILIAS/UI/src/Component/Progress/Bar.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ */
+
+namespace ILIAS\UI\Component\Progress;
+
+use ILIAS\UI\Component\Triggerable;
+use ILIAS\UI\Component\Triggerer;
+use ILIAS\UI\Component\Component;
+use ILIAS\UI\Component\Signal;
+
+/**
+ * @author Thibeau Fuhrer <[email protected]>
+ */
+interface Bar extends Component, Triggerable, Triggerer
+{
+    /**
+     * Get a Signal which can be used to update the current Progress Bar.
+     */
+    public function getUpdateSignal(): Signal;
+
+    /**
+     * Get a Signal which can be used to reset the current Progress Bar.
+     */
+    public function getResetSignal(): Signal;
+}

components/ILIAS/UI/src/Component/Progress/Factory.php

@@ -0,0 +1,92 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ */
+
+namespace ILIAS\UI\Component\Progress;
+
+use ILIAS\Data\URI;
+
+/**
+ * @author Thibeau Fuhrer <[email protected]>
+ */
+interface Factory
+{
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     The Progress Bar is designed to represent the state of a single or bundled task
+     *     or process, which can be processed in a single step and takes a while to finish.
+     *   composition: >
+     *     The Progress Bar is composed out of one horizontal track, the area of which is
+     *     filled according to the current progress (value). It is also accompanied by a label,
+     *     describing the process/task at hand, and a Glyph to indicate a finished status
+     *     (success or failure). An optional message can be displayed, to inform about a
+     *     concrete status.
+     *   effect: >
+     *     When the Progress Bar value is updated, the filled area of the track changes
+     *     accordingly.
+     *     When the Progress Bar is finished, the Glyph changes to one indicating success or
+     *     failure, and an according message will be shown.
+     *   rivals:
+     *     ProgressMeter: use a ProgressMeter if the quality of the progress is evaluated
+     *     and/or the progress is compared.
+     *     Workflow: use a Workflow component if the underlying process/task is completed
+     *     in multiple steps.
+     *
+     * background:
+     *   - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/progress
+     *   - https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role
+     *
+     * rules:
+     *   usage:
+     *     1: >
+     *       The Progress Bar (value) SHOULD NOT be decreased. It should only be reset to 0, if
+     *       the underlying process/task is restarted.
+     *     2: >
+     *       The Progress Bar SHOULD NOT be used, if the underlying process/task can only be
+     *       0% or 100% processed. A loading animation and/or Glyph COULD be used instead.
+     * ---
+     * @param \ILIAS\Data\URI $async_url
+     * @param string          $label
+     * @return \ILIAS\UI\Component\Progress\Bar
+     */
+    public function bar(string $label, ?URI $async_url = null): Bar;
+
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     Instructions are used to communicate with out client during asynchronous requests. They
+     *     are a way to convey information in a manner that is understood by our clientside
+     *     components, and instructs them to perform a desierd change. We have been referring to
+     *     this concept as "HTML over the wire" in the past, and are now implementing it for certain
+     *     components in iterations.
+     *   composition: >
+     *     Instructions consist of HTML structures, typically other (or the same) UI component(s).
+     *   effect: >
+     *     When an Instruction is rendered it will be used by the clientside component to update the
+     *     existing HTML structure according to the Instruction at hand.
+     *
+     * rules:
+     *   usage:
+     *     1: You MUST NOT use Instructions outside of asynchronous requests.
+     *     2: You MUST use @see Renderer::renderAsync() to render Instructions.
+     * ---
+     * @return \ILIAS\UI\Component\Progress\Instruction\Factory
+     */
+    public function instruction(): Instruction\Factory;
+}

components/ILIAS/UI/src/Component/Progress/Instruction/Bar/Factory.php

@@ -0,0 +1,130 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ */
+
+namespace ILIAS\UI\Component\Progress\Instruction\Bar;
+
+use ILIAS\UI\Component\Progress\Instruction\Instruction;
+
+/**
+ * @author Thibeau Fuhrer <[email protected]>
+ */
+interface Factory
+{
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     Factors a Progress Bar Instruction which orders the clientside Progress Bar
+     *     to change its status to "indeterminate". This state indicates that progress
+     *     is being made, but no exact progress can (yet) be calculated. This is
+     *     typically used in order to start the Progress Bar.
+     *   composition: >
+     *     The Instruction consists of an optional message.
+     *   effect: >
+     *     The Progress Bar will change to "indeterminate".
+     *     The Progress Bar shows the given message.
+     *   rivals:
+     *     Determinate: use a determinate Instruction if the progress can be calculated.
+     *
+     * rules:
+     *   usage:
+     *     1: You SHOULD NOT provide a message, if the progress can be calculated soon.
+     *     2: The provided message MUST BE concise and short. E.g. "determining progress".
+     * ---
+     * @param string|null $message
+     * @return Instruction
+     */
+    public function indeterminate(?string $message = null): Instruction;
+
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     Factors a Progress Bar Instruction which orders the clientside Progress Bar
+     *     to change its status to "determinate". This state shows the exact amount of
+     *     progress being made.
+     *   composition: >
+     *     The Instruction consists of a percentage (0-1), representing the exact progress,
+     *     and an optional message.
+     *   effect: >
+     *     The Progress Bar will change to "determinate" and show the progress.
+     *     The Progress Bar shows the given message.
+     *   rivals:
+     *     Indeterminate: use an indeterminate Instruction if the progress cannot be calculated.
+     *     Success: use a success Instruction if the progress is 1 (100%).
+     *     Failure: use a failure Instruction if the underlying task failed.
+     *
+     * rules:
+     *   usage:
+     *     1: The progress percentage MUST BE a floating point number between (0 and 1).
+     *     2: You MUST NOT use this Instruction, if the percentage is 1.
+     *     3: The provided message MUST BE concise and short. E.g. "Processing task XY".
+     * ---
+     * @param float       $progress_percentage
+     * @param string|null $message
+     * @return Instruction
+     */
+    public function determinate(float $progress_percentage, ?string $message = null): Instruction;
+
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     Factors a Progress Bar Instruction which orders the clientside Progress Bar to
+     *     finish with success.
+     *   composition: >
+     *     The Instruction consists of a message.
+     *   effect: >
+     *     The Progress Bar fills up to 100% and shows a success Glyph and the provided
+     *     message.
+     *   rivals:
+     *     Determinate: use a determinate Instruction if the progress is below 100%.
+     *     Failure: use a failure Instruction if the underlying task failed.
+     *
+     * rules:
+     *   usage:
+     *     1: The provided message MUST BE concise and short. E.g. "Task XY done".
+     * ---
+     * @param string $message
+     * @return Instruction
+     */
+    public function success(string $message): Instruction;
+
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     Factors a Progress Bar Instruction which orders the clientside Progress Bar to
+     *     finish with failure.
+     *   composition: >
+     *     The Instruction consists of a message.
+     *   effect: >
+     *     The Progress Bar fills up to 100% and shows a failure Glyph and the provided
+     *     message.
+     *   rivals:
+     *     Determinate: use a determinate Instruction if the progress is below 100%.
+     *     Success: use a success Instruction if the underlying task was successful.
+     *
+     * rules:
+     *   usage:
+     *     1: The provided message MUST BE concise and short. E.g. "Task XY failed."
+     * ---
+     * @param string $message
+     * @return Instruction
+     */
+    public function failure(string $message): Instruction;
+}

components/ILIAS/UI/src/Component/Progress/Instruction/Factory.php

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ */
+
+namespace ILIAS\UI\Component\Progress\Instruction;
+
+/**
+ * @author Thibeau Fuhrer <[email protected]>
+ */
+interface Factory
+{
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     Progress Bar Instructions are used to order a clientside Progress Bar to perform a desired
+     *     update, when pulled asynchronously from a source.
+     *   composition: >
+     *     Progress Bar Instructions cary information about the Progress Bar status and progress (value),
+     *     and optionally provide a message for the user.
+     *
+     * context:
+     *   - Progress Bar Instruction's are used by Progress Bar's which pull updates asynchrnously
+     *     from a source.
+     *
+     * rules:
+     *   usage:
+     *     1: >
+     *       Progress Bar Instructions MUST NOT be used for anything other than updating a
+     *       Progress Bar asynchronously.
+     * ---
+     * @return Bar\Factory
+     */
+    public function bar(): Bar\Factory;
+}

components/ILIAS/UI/src/Component/Progress/Instruction/Instruction.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ */
+
+namespace ILIAS\UI\Component\Progress\Instruction;
+
+use ILIAS\UI\Component\Component;
+
+/**
+ * @author Thibeau Fuhrer <[email protected]>
+ */
+interface Instruction extends Component
+{
+}

components/ILIAS/UI/src/Factory.php

@@ -678,6 +678,36 @@ public function modal(): C\Modal\Factory;
      */
     public function popover(): C\Popover\Factory;
 
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     A Progress component is designed to represent the users advancement within
+     *     a certain process or task. They are of informative nature and provide feedback
+     *     about the current state and said advancement of the process/task. Their goal
+     *     is to guide users by communicating how much of a process/task is completed,
+     *     what remains, and what is ahead of them.
+     *   composition: >
+     *     Progress components are composed out of appropriate scales and status indicators,
+     *     which clearly convey the state of the users advancement.
+     *
+     * rules:
+     *   usage:
+     *     1: A Progress component SHOULD be used whenever a process/task is time-consuming.
+     *     2: >
+     *       A progress component MUST NOT be used to convey any other type of information
+     *       than the users advancement.
+     *   interaction:
+     *     1: Progress components are passive and MUST NOT be operable in any way for the user.
+     *   accessibility:
+     *     1: >
+     *       A progress component MUST be fully accessible using a screen-reader. Any colouring
+     *       or other visual indicators MUST provide according alternative-texts.
+     * ---
+     * @return \ILIAS\UI\Component\Progress\Factory
+     */
+    public function progress(): C\Progress\Factory;
+
     /**
      * ---
      * description:

components/ILIAS/UI/src/Implementation/Factory.php

@@ -25,6 +25,7 @@
 
 // TODO: This might cache the created factories.
 use ILIAS\UI\Implementation\Component\SignalGenerator;
+use ILIAS\UI\NotImplementedException;
 
 class Factory implements \ILIAS\UI\Factory
 {