10/UI/input/duration length

components/ILIAS/UI/src/Component/Input/Field/Factory.php

@@ -797,4 +797,42 @@ public function markdown(MarkdownRenderer $md_renderer, string $label, string $b
      * @return \ILIAS\UI\Component\Input\Field\Rating
      */
     public function rating(string $label, ?string $byline = null): Rating;
+
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *      Use the Length of Time input to ask about durations in various units of time.
+     *   composition: >
+     *      Internally, the input consist of multiple numeric inputs to separate Days, Hours, Minutes etc. into
+     *      multiple fields.
+     *   effect: >
+     *      The fields can be operated like any number field. When a field looses focus, the inputs are transformed to
+     *      show the entered time in a human-readable form given the current field pattern.
+     *      For example: 0 hours, 135 minutes would turn into 2 hours, 15 minutes.
+     *   rivals:
+     *      Duration: >
+     *          This field offers inputs to enter a start and end date (and optionally time). It's the better choice for
+     *          "big picture" planning of events. The Length of Time Field is the right choice for durations with a
+     *          flexible or an unknown start date. It is a good choice for timetable and schedule related items
+     *          where duration matters more than the specific time of day.
+     *
+     * rules:
+     *   wording:
+     *      1: >
+     *          Internally, we avoid calling this Field by the name Duration as it already exists. However, in many
+     *          cases "duration" is actually the best possible label to give. On the frontend you MAY call this field
+     *          using the word "duration".
+     * accessibility:
+     *     1: >
+     *          Aria Live Updates inform Screen Readers about the complete length of time entered throughout all input
+     *          fields after a re-calculation into the more optimal format.
+     *
+     * ---
+     * @param string $label
+     * @param string|null $byline
+     * @param LengthOfTimeFieldPatterns $field_pattern
+     * @return \ILIAS\UI\Component\Input\Field\LengthOfTime
+     */
+    public function lengthOfTime(string $label, ?string $byline = null, LengthOfTimeFieldPatterns $field_pattern = LengthOfTimeFieldPatterns::hoursMinutes): LengthOfTime;
 }

components/ILIAS/UI/src/Component/Input/Field/LengthOfTime.php

@@ -0,0 +1,38 @@
+<?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
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace ILIAS\UI\Component\Input\Field;
+
+use ILIAS\UI\Component\Input\Container\Filter\FilterInput;
+use DateInterval;
+
+/**
+ * This describes the duration input.
+ */
+interface LengthOfTime extends Group, FilterInput
+{
+    /**
+     * Controls which of the fields (days, hours, minutes, seconds) are visible.
+     * @param LengthOfTimeFieldPatterns $field_pattern
+     * @return self
+     */
+    public function withFieldPattern(LengthOfTimeFieldPatterns $field_pattern): self;
+}

components/ILIAS/UI/src/Component/Input/Field/LengthOfTimeFieldPatterns.php

@@ -0,0 +1,28 @@
+<?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
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace ILIAS\UI\Component\Input\Field;
+
+enum LengthOfTimeFieldPatterns: string {
+    case minutesSeconds = 'minutesSeconds';
+    case hoursMinutes = 'hoursMinutes';
+    case hoursMinutesSeconds = 'hoursMinutesSeconds';
+    case daysHoursMinutes = 'daysHoursMinutes';
+}

components/ILIAS/UI/src/Implementation/Component/Input/Field/Factory.php

@@ -20,6 +20,7 @@
 
 namespace ILIAS\UI\Implementation\Component\Input\Field;
 
+use ILIAS\UI\Component\Input\Field\LengthOfTimeFieldPatterns;
 use ILIAS\UI\Implementation\Component\Input\UploadLimitResolver;
 use ILIAS\Data;
 use ILIAS\UI\Component\Input\Container\Form\FormInput;
@@ -243,4 +244,12 @@ public function rating(string $label, string $byline = null): I\Rating
     {
         return new Rating($this->data_factory, $this->refinery, $label, $byline);
     }
+
+    /**
+     * @ineritDoc
+     */
+    public function lengthOfTime(string $label, ?string $byline = null, LengthOfTimeFieldPatterns $field_pattern = LengthOfTimeFieldPatterns::hoursMinutes): LengthOfTime
+    {
+        return new LengthOfTime($this->data_factory, $this->refinery, $this->lng, $this, $label, $byline, $field_pattern);
+    }
 }

components/ILIAS/UI/src/Implementation/Component/Input/Field/Renderer.php

@@ -98,6 +98,9 @@ public function render(Component\Component $component, RendererInterface $defaul
             case ($component instanceof F\Duration):
                 return $this->renderDurationField($component, $default_renderer);
 
+            case ($component instanceof F\LengthOfTime):
+                return $this->renderLengthOfTimeField($component, $default_renderer);
+
             case ($component instanceof F\Link):
                 return $this->renderLinkField($component, $default_renderer);
 
@@ -672,6 +675,13 @@ protected function renderDateTimeField(F\DateTime $component, RendererInterface
         return $this->wrapInFormContext($component, $component->getLabel(), $tpl->get(), $label_id);
     }
 
+    protected function renderLengthOfTimeField(F\LengthOfTime $component, RendererInterface $default_renderer): string
+    {
+        $this->getTemplate("tpl.lengthoftime.html", true, true);
+        $inputs_html = $default_renderer->render($component->getInputs());
+        return $this->wrapInFormContext($component, $component->getLabel(), $inputs_html);
+    }
+
     /**
      * @return array<DateTime,Template>
      */

components/ILIAS/UI/src/examples/Input/Field/LengthOfTime/base.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ILIAS\UI\examples\Input\Field\LengthOfTime;
+
+use DateInterval;
+use ILIAS\UI\Component\Input\Field\LengthOfTimeFieldPatterns;
+use ILIAS\UI\Implementation\Component\Input\Field\LengthOfTime;
+
+/**
+ * ---
+ * description: >
+ *   This example shows how to create and render a basic input field and attach it to a form.
+ *   It does not contain any data processing.
+ *
+ * expected output: >
+ *   ILIAS shows an input field titled "Basic Input". You can enter letters and numbers.
+ * ---
+ */
+function base()
+{
+    global $DIC;
+    $ui = $DIC->ui()->factory();
+    $renderer = $DIC->ui()->renderer();
+
+    $time_interval = DateInterval::createFromDateString("1 hour 37 minutes");
+    $field_pattern = LengthOfTimeFieldPatterns::hoursMinutes;
+
+    $length_of_time_field = $ui->input()->field()->lengthOfTime("Session duration", null, $field_pattern)
+                        ->withValue(["hours" => 1, "minutes" => 97]);
+    $form = $ui->input()->container()->form()->standard(
+        "#",
+        [
+            0 => $length_of_time_field
+        ],
+    );
+
+    return $renderer->render($form);
+}

components/ILIAS/UI/src/templates/default/Input/tpl.lengthoftime.html

@@ -0,0 +1 @@
+<div class="c-input-group">{DURATION}</div>