Update to v0.2.1

book.toml

@@ -4,3 +4,12 @@ language = "en"
 multilingual = false
 src = "src"
 title = "ToolGUI"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/VoileLab/toolgui-doc"
+git-repository-icon = "fa-github"
+
+[output.html.fold]
+enable = true

src/SUMMARY.md

@@ -28,11 +28,12 @@
     * [Subtitle](components/content/subtitle.md)
     * [Text](components/content/text.md)
     * [Image](components/content/image.md)
-    * [Code]()
-    * [Markdown]()
+    * [Code](components/content/code.md)
+    * [Markdown](components/content/markdown.md)
     * [Divider](components/content/divider.md)
     * [Link](components/content/link.md)
     * [Download Button](components/content/download_button.md)
+    * [Latex](components/content/latex.md)
 
 * [Data Components](components/data/index.md)
     * [JSON](components/data/json.md)
@@ -54,8 +55,10 @@
     * [Container](components/layout/container.md)
     * [Box](components/layout/box.md)
     * [Column](components/layout/column.md)
+    * [Expand](components/layout/expand.md)
+    * [Tab](components/layout/tab.md)
 
-* [Misc Components]()
-    * [Echo]()
-    * [Message]()
-    * [Progress Bar]()
+* [Misc Components](components/misc/index.md)
+    * [Echo](components/misc/echo.md)
+    * [Message](components/misc/message.md)
+    * [Progress Bar](components/misc/progress_bar.md)

src/app/index.md

@@ -2,7 +2,7 @@
 
 The App includes the info of
 
-1. [Navbar](navbar.md)
+1. [Navbar](navbar.md): The navbar is the topmost part of the app.
 2. [Pages](page.md): The App hold a ordered map from page name to page's data.
 
 ![layout](layout.png)

src/app/navbar.md

@@ -8,6 +8,6 @@ The left part will be buttons which nav to the pages in App.
 The right part will be two button:
 
 1. Rerun: Rerun the Page Func without changing any state.
-2. Dark/Light Mode Switch
+2. Dark/Light Mode Switch: Switch the theme of the app.
 
 The button of current page will be highlighted with a specific style.

src/architecture/state-cache.md

@@ -3,26 +3,31 @@
 State-level cache stores data specific to the current view or "page" displayed to the user.
 This data lost when the user navigates away from the page or refreshes it.
 
+## Example of variable
+
 Here we provide a state-level TODO App example.
 It stores list of todos in the state:
 
 ```go
+type TODOList struct {
+	items []string
+}
+
+func (t *TODOList) add(item string) {
+	t.items = append(t.items, item)
+}
+
 func Main(p *tgframe.Params) error {
 	tgcomp.Title(p.Main, "Example for Todo App")
 
-	var todos []string
-	err := p.State.GetObject("todos", &todos)
-	if err != nil {
-		return err
-	}
+	todoList := p.State.Default("todoList", &TODOList{}).(*TODOList)
 
 	inp := tgcomp.Textbox(p.State, p.Main, "Add todo")
 	if tgcomp.Button(p.State, p.Main, "Add") {
-		todos = append(todos, inp)
-		p.State.Set("todos", todos)
+		todoList.add(inp)
 	}
 
-	for i, todo := range todos {
+	for i, todo := range todoList.items {
 		tgcomp.TextWithID(p.Main,
 			fmt.Sprintf("%d: %s", i, todo),
 			fmt.Sprintf("todo_%d", i))
@@ -31,3 +36,57 @@ func Main(p *tgframe.Params) error {
 	return nil
 }
 ```
+
+## Example of function
+
+Here we provide a state-level cache for a function.
+
+```go
+// getFiles unarchive cbz file and return list of file names,
+// since unarchive is time-consuming, we use state-level cache to store the result
+func getFiles(p *tgframe.Params, f *tcinput.FileObject) ([]string, error) {
+	key := fmt.Sprintf("%s_%s_%x", f.Name, f.Type, md5.Sum(f.Bytes))
+
+	v := p.State.GetFuncCache(key)
+	if v != nil {
+		slog.Debug("cache found")
+		return v.([]string), nil
+	}
+
+	buf := bytes.NewReader(f.Bytes)
+
+	cbzFp, err := zip.NewReader(buf, buf.Size())
+	if err != nil {
+		// don't store nil to cache
+		return nil, err
+	}
+
+	ret := []string{}
+	for _, f := range cbzFp.File {
+		ret = append(ret, f.Name)
+	}
+
+	// ok, we can store to cache
+	p.State.SetFuncCache(key, ret)
+	return ret, nil
+}
+
+func FuncCachePage(p *tgframe.Params) error {
+	cbzfile := tgcomp.Fileupload(p.State, p.Sidebar, "CBZ File", "application/x-cbz")
+
+	if cbzfile == nil {
+		return nil
+	}
+
+	files, err := getFiles(p, cbzfile)
+	if err != nil {
+		return err
+	}
+
+	for i, f := range files {
+		tgcomp.Text(p.Main, fmt.Sprintf("%d: %s", i, f))
+	}
+
+	return nil
+}
+```

src/components/content/code.md

@@ -0,0 +1,41 @@
+# Code
+
+## API
+
+### Interface
+
+```go
+func Code(c *tgframe.Container, code string)
+func CodeWithConf(c *tgframe.Container, code string, conf *CodeConf)
+```
+
+### Parameters
+
+* `c`: Parent container.
+* `code`: Code to display.
+* `conf`: Configuration for the code component.
+
+```go
+// CodeConf provide extra config for Code Component.
+type CodeConf struct {
+	// Language is language of code block, leave empty to use `go`
+	Language string
+
+	// ID is id of the component
+	ID string
+}
+```
+
+## Example
+
+```go
+tgcomp.Code(c, "package main\n\nfunc main() {\n\tprintln(\"Hello, World!\")")
+```
+
+```go
+tgcomp.CodeWithConf(c, "package main\n\nfunc main() {\n\tprintln(\"Hello, World!\")",
+    &tgcomp.CodeConf{
+        Language: "go",
+        ID:       "mycode",
+    })
+```

src/components/content/download_button.md

@@ -4,15 +4,39 @@ DownloadButton create a download button component.
 
 ## API
 
+### Interface
+
 ```go
 func DownloadButton(c *tgframe.Container, text string, body []byte, filename string)
-func DownloadButtonWithID(c *tgframe.Container, text string, body []byte, filename, id string)
+func DownloadButtonWithConf(c *tgframe.Container, conf *tgcomp.DownloadButtonConf)
 ```
 
+### Parameters
+
 * `c` is Parent container.
 * `text` is the link text.
 * `body` is the bytes of file.
-* `id` is a user specific element id.
+* `filename` is the file name.
+* `conf` is the configuration of the download button.
+
+```go
+type DownloadButtonConf struct {
+	// MIME specifies the Multipurpose Internet Mail Extension (MIME) type of the downloaded content.
+	// Defaults to "application/octet-stream" if not provided.
+	MIME string
+
+	// Color defines the color of the download button.
+	Color tcutil.Color
+
+	// Disabled indicates whether the download button should be initially disabled.
+	Disabled bool
+
+	// Filename sets the suggested filename for the downloaded content when clicked.
+	Filename string
+
+	ID string
+}
+```
 
 ## Example
 

src/components/content/image.md

@@ -4,21 +4,43 @@ Image component display an image.
 
 ## API
 
+### Interface
+
 ```go
-func Image(c *tgframe.Container, img image.Image)
-func ImageByURI(c *tgframe.Container, uri string)
+func Image(c *tgframe.Container, img any)
+func ImageWithConf(c *tgframe.Container, img any, conf *tgcomp.ImageConf)
 ```
 
+### Parameters
+
 * `c` is Parent container.
 * `img` is the image.
-* `uri` is the URI form of the image. Example:
-  * URL: `https://http.cat/100`
-  * base64 uri: `data:image/png;base64,...`
+  * `image.Image`: an image.Image
+  * `[]byte`: a byte array
+  * `string`: a url or base64 encoded image
+    * example:
+      * url: `https://http.cat/100`
+      * base64 uri: `data:image/png;base64,...`
+* `conf` is the configuration of the image.
+
+```go
+// ImageConf is the configuration for the Image component
+type ImageConf struct {
+	// Width is the width of the image (e.g. "100px", "50%")
+	Width string
+
+	// Format is the format of the image, default is "png"
+	Format ImageFormat
+
+	// ID is the unique identifier for this image component
+	ID string
+}
+```
 
 ## Example
 
 ```go
-tgcomp.ImageByURI(p.Main, "https://http.cat/100")
+tgcomp.Image(p.Main, "https://http.cat/100")
 ```
 
 ![image component](image.png)

src/components/content/index.md

@@ -3,5 +3,9 @@
 The content components show basic content.
 It doesn't return any value to user.
 
+```go
+import "github.com/VoileLab/toolgui/toolgui/tgcomp"
+```
+
 The demo page can be found here:
 [https://toolgui-demo.fly.dev/content](https://toolgui-demo.fly.dev/content)

src/components/content/latex.md

@@ -0,0 +1,19 @@
+# Latex
+
+Latex component is used to display LaTeX content.
+
+## API
+
+```go
+func Latex(c *tgframe.Container, latex string)
+```
+
+* `c` is the container to add the LaTeX component to.
+* `latex` is the LaTeX content to display.
+
+## Example
+
+```go
+tgcomp.Latex(c, "E = mc^2")
+```
+

src/components/content/markdown.md

@@ -0,0 +1,26 @@
+# Markdown
+
+## API
+
+### Interface
+
+```go
+func Markdown(c *tgframe.Container, markdown string)
+func MarkdownWithID(c *tgframe.Container, markdown string, id string)
+```
+
+### Parameters
+
+* `c`: Parent container.
+* `markdown`: Markdown content to display.
+* `id`: Unique component ID.
+
+## Example
+
+```go
+tgcomp.Markdown(c, "* Hello, World!")
+```
+
+```go
+tgcomp.MarkdownWithID(c, "* Hello, World!", "my-markdown")
+```

src/components/data/json.md

@@ -10,6 +10,8 @@ func JSON(c *tgframe.Container, v any)
 
 * `c` is Parent container.
 * `v` is the object.
+  * string: assume to be a serialized JSON string.
+  * other: assume to be a struct and will be converted to a JSON string.
 
 ## Example
 

src/components/input/button.md

@@ -6,11 +6,27 @@ Button create a button and return true if it's clicked.
 
 ```go
 func Button(s *tgframe.State, c *tgframe.Container, label string) bool
+func ButtonWithConf(s *tgframe.State, c *tgframe.Container, conf *tgcomp.ButtonConf) bool
 ```
 
 * `s` is State.
 * `c` is Parent container.
 * `label` is the text on button.
+* `conf` is the configuration of the button.
+
+```go
+// ButtonConf is the configuration for the Button component
+type ButtonConf struct {
+	// Color defines the color of the button
+	Color tcutil.Color
+
+	// Disabled indicates whether the button should be initially disabled
+	Disabled bool
+
+	// ID is the unique identifier for this button component
+	ID string
+}
+```
 
 ## Example