ListBox helper added

Author: spirali

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## New features
 
 * text itself can be `InSteps`
+* `ListBox` helper added
 
 
 # 0.4

docs/guide/list.md

@@ -0,0 +1,77 @@
+# List
+
+Lists are not build-in in Nelsie. You can create lists manually, or you can create
+a helper class `ListBox` for creating lists.
+
+`ListBox` takes a box as a first parameter and creates list in this box.
+`ListBox` behaves as a normal vertical box but creates a bullet for each child.
+
+## Unordered list
+
+```nelsie
+from nelsie.helpers.list import ListBox
+
+@deck.slide()
+def list_demo(slide):
+    slide.set_style("default", TextStyle(size=80))
+    lst = ListBox(slide)
+    lst.text("First item")
+    lst.text("Second item")
+    lst.text("Third item")
+```
+
+## Ordered list
+
+You can change type of by setting a second argument `list_type` to following values:
+
+- `"unordered"` (default) - Unordered list
+- `"1"` - Ordered list, 1., 2., 3. ...
+- `"a"` - Ordered list, a., b., c. ...
+- `"A"` - Ordered list, A., B., C. ...
+
+```nelsie
+from nelsie.helpers.list import ListBox
+
+@deck.slide()
+def list_demo(slide):
+    slide.set_style("default", TextStyle(size=80))
+    lst = ListBox(slide, "1")
+    lst.text("First item")
+    lst.text("Second item")
+    lst.text("Third item")
+```
+
+
+```nelsie
+from nelsie.helpers.list import ListBox
+
+@deck.slide()
+def list_demo(slide):
+    slide.set_style("default", TextStyle(size=80))
+    lst = ListBox(slide, "a")
+    lst.text("First item")
+    lst.text("Second item")
+    lst.text("Third item")
+```
+
+
+## Sublists
+
+A sublist can be created by calling `.list()` method on an existing `ListBox`.
+It returns an instance of `ListBox`.
+
+```nelsie
+from nelsie.helpers.list import ListBox
+
+@deck.slide()
+def list_demo(slide):
+    slide.set_style("default", TextStyle(size=80))
+
+    lst = ListBox(slide)
+    lst.text("First item")
+    lst.text("Second item")
+
+    lst2 = lst.list()
+    lst2.text("Hello")
+    lst2.text("World!")
+```

mkdocs.yml

@@ -29,6 +29,7 @@ nav:
       - guide/resources.md
       - guide/box.md
       - guide/colors.md
+      - guide/list.md
 
 theme:
   name: material

python/nelsie/helpers/list.py

@@ -0,0 +1,54 @@
+from typing import Callable
+
+from ..box import Box, BoxBuilder
+
+
+DEFAULT_BULLETS = ("•", "⁃", "‣")
+
+
+class ListBox(BoxBuilder):
+    def __init__(
+        self, parent_box: Box, list_type: str | Callable = "unordered", style="default", indent_size=1.1, counters=None
+    ):
+        self.main_box = parent_box.box(align_items="start")
+        if isinstance(style, str):
+            style = parent_box.get_style(style)
+        self.style = style
+        self.indent_size = indent_size * style.size
+        self.list_type = list_type
+        if counters is None:
+            self.counters = [0]
+        else:
+            self.counters = counters[:] + [0]
+
+    @property
+    def level(self):
+        return len(self.counters) - 1
+
+    def get_box(self):
+        return self.main_box
+
+    def create_item_boxes(self, box_args) -> (Box, Box):
+        item_box = self.main_box.box(row=True, align_items="start")
+        box1 = item_box.box(row=True, width=self.indent_size, justify_content="start")
+        box2 = item_box.box(**box_args)
+        return box1, box2
+
+    def box(self, **box_args) -> Box:
+        self.counters[-1] += 1
+        box1, box2 = self.create_item_boxes(box_args)
+        if isinstance(self.list_type, Callable):
+            self.list_type(box1)
+        elif self.list_type == "unordered":
+            box1.text(DEFAULT_BULLETS[self.level % len(DEFAULT_BULLETS)], style=self.style)
+        elif self.list_type == "1":
+            box1.text(f"{self.counters[-1]}.", style=self.style)
+        elif self.list_type == "a":
+            box1.text(f"{chr(ord('a') - 1 + self.counters[-1])}.", style=self.style)
+        elif self.list_type == "A":
+            box1.text(f"{chr(ord('A') - 1 + self.counters[-1])}.", style=self.style)
+        return box2
+
+    def list(self, list_type="unordered", **box_args):
+        box1, box2 = self.create_item_boxes(box_args)
+        return ListBox(box2, list_type=list_type, counters=self.counters)

tests/checks/list/0-1.png

@@ -0,0 +1,32 @@
+from nelsie import TextStyle
+from nelsie.helpers.list import ListBox
+from testutils import check
+
+
+@check()
+def test_list(deck):
+    slide = deck.new_slide(width=200, height=300)
+    slide.set_style("default", TextStyle(size=12))
+    lst = ListBox(slide)
+    lst.text("One")
+    lst.text("Two1\nTwo2\nTwo3")
+    lst.text("Long item three")
+    lst2 = lst.list()
+    lst2.text("A")
+    lst2.text("BB")
+    lst2.text("CCC")
+    lst2 = lst.list(list_type="1")
+    lst2.text("A")
+    lst2.text("BB")
+    lst2.text("CCC")
+    lst2 = lst.list(list_type="a")
+    lst2.text("A")
+    lst2.text("BB")
+    lst2.text("CCC")
+    lst2 = lst.list(list_type="A")
+    lst2.text("A")
+    lst2.text("BB")
+    lst2.text("CCC")
+    lst3 = lst2.list()
+    lst3.text("Hello!")
+    lst.text("Fourth item")