feat(leaves): add Paginator component (#37)

* WIP

* Paginator: view

* Paginator working

* Paginator demo

* Paginator demo update

* Paginator demo update again

* Paginator: mli file done

* Paginator: fixed the formatting type ;)

* Paginator: finish docs

Author: metame

examples/paginator/demo.gif

@@ -0,0 +1,26 @@
+Output demo.gif
+
+Require echo
+
+Set Shell "bash"
+Set Framerate 24
+Set FontSize 32
+Set Width 1200
+Set Height 600
+
+Type "dune exec --no-print-directory ./main.exe"
+Enter
+Sleep 1s
+Right
+Sleep 1s
+Right
+Sleep 1s
+Right
+Sleep 1s
+Left
+Sleep 1s
+Left
+Sleep 1s
+Left
+Sleep 1s
+Type @0.s "q"

examples/paginator/demo.tape

@@ -0,0 +1,3 @@
+(executable
+ (name main)
+ (libraries minttea spices leaves))

examples/paginator/dune

@@ -0,0 +1,30 @@
+open Minttea
+open Leaves
+
+type model = { paginator : Paginator.t; items : string list }
+
+let items = List.init 9 (fun x -> "Item " ^ string_of_int (x + 1))
+let paginator = Paginator.make ~per_page:3 ~style:Paginator.Dots ()
+let paginator, _ = Paginator.set_total_pages paginator 9
+let initial_model = { paginator; items }
+let init _ = Command.Hide_cursor
+
+let update (event : Event.t) model =
+  match event with
+  | Event.KeyDown (Key "q") -> (model, Command.Quit)
+  | _ ->
+      ( { model with paginator = Paginator.update model.paginator event },
+        Command.Noop )
+
+let view model =
+  let start, end_pos = Paginator.get_slice_bounds model.paginator 9 in
+  let x = List.to_seq model.items in
+  let y = Seq.drop start x in
+  let z = Seq.take (end_pos - start) y in
+  "\n Look! We have 9 items!\n\n "
+  ^ String.concat "\n " (List.of_seq z)
+  ^ Format.sprintf "\n %s\n" (Paginator.view model.paginator)
+  ^ "\n h/l ←/→ page • q: quit\n"
+
+let app = Minttea.app ~init ~update ~view ()
+let () = Minttea.start ~initial_model app

examples/paginator/main.ml

@@ -0,0 +1,79 @@
+type style = Dots | Numerals
+
+type t = {
+  style : style;
+  page : int;
+  per_page : int;
+  total_pages : int;
+  active_dot : string;
+  inactive_dot : string;
+  numerals_format : (int -> int -> string, unit, string) format;
+  text_style : Spices.style;
+}
+
+let set_total_pages t items =
+  if items < 1 then (t, t.total_pages)
+  else
+    let n = items / t.per_page in
+    let n = if items mod t.per_page > 0 then n + 1 else n in
+    let new_t = { t with total_pages = n } in
+    (new_t, n)
+
+let get_slice_bounds t length =
+  let start = t.page * t.per_page in
+  let end_pos = min ((t.page * t.per_page) + t.per_page) length in
+  (start, end_pos)
+
+let items_on_page t total_items =
+  if total_items < 1 then 0
+  else
+    let start, end_pos = get_slice_bounds t total_items in
+    end_pos - start
+
+let on_last_page t = t.page = t.total_pages - 1
+let on_first_page t = t.page = 0
+let prev_page t = { t with page = max (t.page - 1) 0 }
+let next_page t = if on_last_page t then t else { t with page = t.page + 1 }
+
+let make ?(style = Numerals) ?(page = 0) ?(per_page = 1) ?(total_pages = 1)
+    ?(active_dot = "•") ?(inactive_dot = "○")
+    ?(numerals_format : (int -> int -> string, unit, string) format = "%d/%d")
+    ?(text_style = Spices.default) () =
+  {
+    style;
+    page;
+    per_page;
+    total_pages;
+    active_dot;
+    inactive_dot;
+    numerals_format;
+    text_style;
+  }
+
+let update t (e : Minttea.Event.t) =
+  match e with
+  | KeyDown (Key "h" | Left) -> prev_page t
+  | KeyDown (Key "l" | Right) -> next_page t
+  | _ -> t
+
+let dots_view t text_style =
+  let text_style = text_style |> Spices.build in
+  let result = ref "" in
+  for i = 0 to t.total_pages - 1 do
+    let dot =
+      if i == t.page then text_style "%s" t.active_dot
+      else text_style "%s" t.inactive_dot
+    in
+    result := !result ^ dot
+  done;
+  !result
+
+let numerals_view t text_style =
+  let text_style = text_style |> Spices.build in
+  let txt = Format.sprintf t.numerals_format (t.page + 1) t.total_pages in
+  text_style "%s" txt
+
+let view t =
+  match t.style with
+  | Dots -> dots_view t t.text_style
+  | Numerals -> numerals_view t t.text_style

leaves/paginator.ml

@@ -0,0 +1,116 @@
+type style = Dots | Numerals
+type t
+
+val set_total_pages : t -> int -> t * int
+(** [set_total_pages paginator total] calculates the total number of pages
+from a given number of items. Its use is optional since this pager can be
+used for other things beyond navigating sets. Note that it both returns the
+number of total pages and alters the model.
+
+    {@ocaml[
+      let paginator = Paginator.make () in
+      let total_pages, paginator = Paginator.set_total_pages paginator 3
+    ]}
+ *)
+
+val get_slice_bounds : t -> int -> int * int
+(**  [get_slice_bounds paginator item_count] returns the start and end bounds of slice you're
+     rendering for the current page based on total number of items
+
+     {@ocaml[
+       let bunch_of_stuff = List.to_seq [...] in
+       let start, end_pos = Paginator.get_slice_bounds (Seq.length bunch_of_stuff) in
+       let slice_to_render = Seq.take (end_pos - start) @@ Seq.drop start bunch_of_stuff
+     ]}
+ *)
+
+val items_on_page : t -> int -> int
+(** [items_on_page paginator items_count] returns the number of items on the
+    current page given the total number of items passed as an argument.
+
+    {@ocaml[
+      let paginator = Paginator.make () in
+      let item_count = Paginator.items_on_page paginator 10
+    ]}
+ *)
+
+val on_last_page : t -> bool
+(** [on_last_page paginator] returns whether or not we're on the last page.
+
+    {@ocaml[
+      let paginator = Paginator.make () in
+      Paginator.on_last_page paginator
+    ]}
+ *)
+
+val on_first_page : t -> bool
+(** [on_first_page paginator] returns whether or not we're on the first page.
+
+    {@ocaml[
+      let paginator = Paginator.make () in
+      Paginator.on_first_page paginator
+    ]}
+ *)
+
+val prev_page : t -> t
+(** [prev_page paginator] navigates one page backward with a lower bound of 0.
+
+    {@ocaml[
+      let paginator = Paginator.make () in
+      let paginator = Paginator.prev_page paginator
+    ]}
+ *)
+
+val next_page : t -> t
+(** [next_page paginator] navigates one page forward with an upper bound of total_pages - 1.
+
+    {@ocaml[
+      let paginator = Paginator.make () in
+      let paginator = Paginator.next_page paginator
+    ]}
+ *)
+
+val make :
+  ?style:style ->
+  ?page:int ->
+  ?per_page:int ->
+  ?total_pages:int ->
+  ?active_dot:string ->
+  ?inactive_dot:string ->
+  ?numerals_format:(int -> int -> string, unit, string) format ->
+  ?text_style:Spices.style ->
+  unit ->
+  t
+(** [make ()] creates a new {Paginator.t}
+
+    A different start page can be specified using `page`.
+
+    For helper functions like `get_slice_bounds` to work correctly, the number of items to be rendered on each page can be passed to `per_page`.
+
+    By default, Paginator uses Numerals format, displaying page 1 of 3 as "1/3".
+    The format for numerals can be changed using `numerals_format` to any format that takes two integers, e.g. "%d of %d" rendering "1 of 3" instead.
+    Alternatively, `style` can be specified as `Paginator.Dots` to display pages using characters instead with the `active_dot` "•" and inactive_dot "○" defaults, which can be specified/overriden.
+
+    By default, Spices.default is used, which can be overriden using `text_style`.
+
+    {@ocaml[
+      let paginator = Paginator.make ()
+    ]}
+ *)
+
+val update : t -> Minttea.Event.t -> t
+(** [update paginator event] is the Tea update function which binds keystrokes to pagination.
+
+    {@ocaml[
+      let paginator = Paginator.update paginator event
+    ]}
+ *)
+
+val view : t -> string
+(** [view paginator] renders the pagination to a string.
+
+    {@ocaml[
+      let paginator = Paginator.make () in
+      let pagination_string = Paginator.view paginator
+    ]}
+ *)