UI/Navigation: remove builder, introduce legacySegment

components/ILIAS/UI/src/Component/Image/Image.php

@@ -25,15 +25,14 @@
 use ILIAS\UI\Component\Signal;
 use ILIAS\UI\Component\Component;
 use ILIAS\UI\Component\Layout\Alignment\Block;
-use ILIAS\UI\Component\Navigation\Sequence\IsSegmentContent;
 
 /**
  * This describes how a glyph could be modified during construction of UI.
  *
  * Interface Image
  * @package ILIAS\UI\Component\Image
  */
-interface Image extends Component, JavaScriptBindable, Clickable, Block, IsSegmentContent
+interface Image extends Component, JavaScriptBindable, Clickable, Block
 {
     /**
      * Types of images

components/ILIAS/UI/src/Component/Input/Container/Form/Standard.php

@@ -21,12 +21,11 @@
 namespace ILIAS\UI\Component\Input\Container\Form;
 
 use ILIAS\UI\Component\Prompt\IsPromptContent;
-use ILIAS\UI\Component\Navigation\Sequence\IsSegmentContent;
 
 /**
  * This describes a standard form.
  */
-interface Standard extends FormWithPostURL, IsPromptContent, IsSegmentContent
+interface Standard extends FormWithPostURL, IsPromptContent
 {
     /**
      * Sets the label of the submit button of the form

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

@@ -47,4 +47,28 @@ interface Factory
      */
     public function legacyContent(string $content): LegacyContent;
 
+    /**
+     * ---
+     * description:
+     *   purpose: >
+     *     The legacy segment is used as container for visible content in
+     *     the context of sequence nvigations.
+     *     We currently lack quite a lot of UI components for describing the
+     *     actual contents of the page, e.g. questions, combinations of text/table/form, etc.
+     *     Until these components exist an enable us to better describe the
+     *     correlations to navigations, the legacy segment is used to contain
+     *     rendered HTML.
+     *   composition: >
+     *     The legacy segment contains html (or any other content) as string;
+     *     it also has a title.
+     *
+     * context:
+     *   - A segment is the content affected by operating the sequence navigation.
+     * ---
+     * @param string $title the title of the legacy segment
+     * @param string $content the content of the legacy segment
+     * @return \ILIAS\UI\Component\Legacy\LegacySegment
+     */
+    public function legacySegment(string $title, string $content): LegacySegment;
+
 }

components/ILIAS/UI/src/Implementation/Component/Navigation/Sequence/SegmentBuilder.php → components/ILIAS/UI/src/Component/Legacy/LegacySegment.php

@@ -18,16 +18,18 @@
 
 declare(strict_types=1);
 
-namespace ILIAS\UI\Implementation\Component\Navigation\Sequence;
+namespace ILIAS\UI\Component\Legacy;
 
-use ILIAS\UI\Component\Navigation\Sequence as ISequence;
+use ILIAS\UI\Component\Component;
+use ILIAS\UI\Component\Navigation\Sequence\Segment;
+use ILIAS\UI\Component\Button;
 
-class SegmentBuilder implements ISequence\SegmentBuilder
+interface LegacySegment extends Component, Segment
 {
-    public function build(
-        string $title,
-        ISequence\IsSegmentContent ...$contents
-    ): ISequence\Segment {
-        return new Segment($title, ...$contents);
-    }
+    /**
+     * Segments MAY add actions to the sequence.
+     * Those actions MUST target the actually displayed contents rather
+     * than changing context entirely (i.e. breaking the sequence).
+     */
+    public function withSegmentActions(Button\Standard ...$actions): static;
 }

components/ILIAS/UI/src/Component/Listing/CharacteristicValue/Text.php

@@ -22,12 +22,11 @@
 
 use ILIAS\UI\Component\Component;
 use ILIAS\UI\Component\Layout\Alignment\Block;
-use ILIAS\UI\Component\Navigation\Sequence\IsSegmentContent;
 
 /**
  * Interface Text
  */
-interface Text extends Component, Block, IsSegmentContent
+interface Text extends Component, Block
 {
     /**
      * Gets the items as array of key value pairs for the list.

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

@@ -26,18 +26,18 @@ interface Factory
      * ---
      * description:
      *   purpose: >
-     *      The Sequence Navigation is used to guide users through a process in a
-     *      structured manner, ensuring they complete tasks or gather information
-     *      in the intended order.
-     *      Elements (or the amount of) may change during the process, however,
+     *      The Sequence Navigation is used to move through a series of elements
+     *      in a particular order.
+     *      Elements (or the amount of) may change during navigation, however,
      *      they will remain in a consecutive order.
      *   composition: >
      *      Sequence Navigation consists of several groups of buttons, mainly.
      *      First of all, there is the primary navigation of back- and next buttons
      *      to navigate through the parts of the sequence; a part is called a "Segment".
-     *      While every Segment of a sequence is part of a bigger process, there
-     *      might be additional buttons for actions targeting this outer context, or
-     *      terminating the browsing of the sequence.
+     *      While every Segment of a sequence is part of a bigger process (i.e.
+     *      the perception of the entire sequence), there might be additional buttons
+     *      for actions targeting outer context, or terminating the browsing
+     *      of the sequence.
      *      Every shown segement may also add buttons with actions regarding the
      *      current segement.
      *      Finally, there may be view controls and filters to change the amount of

components/ILIAS/UI/src/Component/Navigation/Sequence/Binding.php

@@ -40,7 +40,6 @@ public function getSequencePositions(
      * Receives position data (provided by getSequencePositions) and builds a segment.
      */
     public function getSegment(
-        SegmentBuilder $builder,
         mixed $position_data,
         array $viewcontrol_values,
         array $filter_values

components/ILIAS/UI/src/Component/Navigation/Sequence/Segment.php

@@ -20,6 +20,8 @@
 
 namespace ILIAS\UI\Component\Navigation\Sequence;
 
+use ILIAS\UI\Component\Button;
+
 /**
  * A segment is the content resulting from operating a sequence.
  */
@@ -28,19 +30,18 @@ interface Segment
     /**
      * A segment provides a title
      */
-    public function getTitle(): string;
+    public function getSegmentTitle(): string;
 
     /**
      * The actual "contents" of the displayed view when operating a sequence.
-     * Valid Components are flagged with the IsSegmentContent interface.
-     * @return IsSegmentContent[]
      */
-    public function getContents(): array;
+    public function getSegmentContent(): string;
 
     /**
      * Segments MAY add actions to the sequence.
      * Those actions MUST target the actually displayed contents rather
      * than changing context entirely (i.e. breaking the sequence).
+     * @return Button\Standard[]
      */
-    public function withActions(...$actions): static;
+    public function getSegmentActions(): ?array;
 }

components/ILIAS/UI/src/Component/Table/Table.php

@@ -21,9 +21,8 @@
 namespace ILIAS\UI\Component\Table;
 
 use ILIAS\UI\Component\Component;
-use ILIAS\UI\Component\Navigation\Sequence\IsSegmentContent;
 
-interface Table extends Component, IsSegmentContent
+interface Table extends Component
 {
     public function withTitle(string $title): self;
 

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

@@ -39,4 +39,12 @@ public function legacyContent(string $content): C\Legacy\LegacyContent
     {
         return new LegacyContent($content, $this->signal_generator);
     }
+
+    /**
+     * @inheritdoc
+     */
+    public function legacySegment(string $title, string $content): C\Legacy\LegacySegment
+    {
+        return new LegacySegment($title, $content);
+    }
 }

components/ILIAS/UI/src/Implementation/Component/Navigation/Sequence/Segment.php → components/ILIAS/UI/src/Implementation/Component/Legacy/LegacySegment.php

@@ -18,44 +18,43 @@
 
 declare(strict_types=1);
 
-namespace ILIAS\UI\Implementation\Component\Navigation\Sequence;
+namespace ILIAS\UI\Implementation\Component\Legacy;
 
-use ILIAS\UI\Component\Navigation\Sequence as ISequence;
+use ILIAS\UI\Component\Legacy\LegacySegment as ISegment;
+use ILIAS\UI\Implementation\Component\ComponentHelper;
+use ILIAS\UI\Component\Button;
 
-class Segment implements ISequence\Segment
+class LegacySegment implements ISegment
 {
+    use ComponentHelper;
+
     protected ?array $actions = null;
 
-    /**
-     * @var ISequence\IsSegmentContent[]
-     */
-    protected array $contents;
 
     public function __construct(
         protected string $title,
-        ISequence\IsSegmentContent ...$contents,
+        protected string $content
     ) {
-        $this->contents = $contents;
     }
 
-    public function getContents(): array
+    public function getSegmentTitle(): string
     {
-        return $this->contents;
+        return $this->title;
     }
 
-    public function getTitle(): string
+    public function getSegmentContent(): string
     {
-        return $this->title;
+        return $this->content;
     }
 
-    public function withActions(...$actions): static
+    public function withSegmentActions(Button\Standard ...$actions): static
     {
         $clone = clone $this;
         $clone->actions = $actions;
         return $clone;
     }
 
-    public function getActions(): ?array
+    public function getSegmentActions(): ?array
     {
         return $this->actions;
     }

components/ILIAS/UI/src/Implementation/Component/Legacy/Renderer.php

@@ -35,10 +35,19 @@ class Renderer extends AbstractComponentRenderer
      */
     public function render(Component\Component $component, RendererInterface $default_renderer): string
     {
-        if (!$component instanceof Component\Legacy\LegacyContent) {
-            $this->cannotHandleComponent($component);
+        if ($component instanceof Component\Legacy\LegacyContent) {
+            return $this->renderLegacyContent($component, $default_renderer);
         }
+        if ($component instanceof Component\Legacy\LegacySegment) {
+            return $this->renderLegacySegment($component, $default_renderer);
+        }
+
+        $this->cannotHandleComponent($component);
 
+    }
+
+    protected function renderLegacyContent(LegacyContent $component, RendererInterface $default_renderer): string
+    {
         $component = $this->registerSignals($component);
         $this->bindJavaScript($component);
         return $component->getContent();
@@ -58,4 +67,10 @@ protected function registerSignals(LegacyContent $component): Component\JavaScri
             return $code;
         });
     }
+
+    protected function renderLegacySegment(LegacySegment $component, RendererInterface $default_renderer): string
+    {
+        return 'a legacy segment is not rendered by itself, it\'s used with sequence navigation';
+    }
+
 }

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

@@ -40,7 +40,6 @@ public function sequence(
         INavigation\Sequence\Binding $binding
     ): INavigation\Sequence\Sequence {
         return new Sequence\Sequence(
-            new Sequence\SegmentBuilder(),
             $this->data_factory,
             $this->refinery,
             $this->storage,

components/ILIAS/UI/src/Implementation/Component/Navigation/Sequence/Renderer.php

@@ -60,7 +60,6 @@ protected function renderSequence(
         }
 
         $segment = $component->getBinding()->getSegment(
-            $component->getSegmentBuilder(),
             $positions[$position],
             $vc_data,
             $filter_data
@@ -82,15 +81,16 @@ protected function renderSequence(
             $tpl->setVariable('VIEWCONTROLS', $default_renderer->render($viewcontrols));
         }
 
-        if ($actions = $segment->getActions()) {
-            $tpl->setVariable('ACTIONS_SEGMENT', $default_renderer->render($actions));
-        }
         if ($actions = $component->getActions()) {
             $tpl->setVariable('ACTIONS_GLOBAL', $default_renderer->render($actions));
         }
 
-        $tpl->setVariable('SEGMENT_TITLLE', $segment->getTitle());
-        $tpl->setVariable('SEGMENT_CONTENTS', $default_renderer->render($segment->getContents()));
+        if ($actions = $segment->getSegmentActions()) {
+            $tpl->setVariable('ACTIONS_SEGMENT', $default_renderer->render($actions));
+        }
+
+        $tpl->setVariable('SEGMENT_TITLLE', $segment->getSegmentTitle());
+        $tpl->setVariable('SEGMENT_CONTENTS', $segment->getSegmentContent());
         return $tpl->get();
     }
 }