diff --git a/docs/Components.md b/docs/Components.md new file mode 100644 index 0000000..3e02551 --- /dev/null +++ b/docs/Components.md @@ -0,0 +1,63 @@ +# Components + +Overview of what terminal-ui provides. All entry points are on `Terminal.*`. + +## Output & text + +| API | Description | +|-----|-------------| +| `Terminal.print(String)` | Styled text (chain `.color()`, `.bold()`, `.println()`) | +| `Terminal.rule()` | Horizontal rule (e.g. `====`) | +| `Terminal.keyValue()` | Key-value pairs | +| `Terminal.box()` | Box around content | + +## Tables & layout + +| API | Description | +|-----|-------------| +| `Terminal.table()` | Tables with header/rows | +| `Terminal.tree()` | Tree structure | +| `Terminal.columns()` | Multi-column layout | +| `Terminal.steps()` | Step indicator | +| `Terminal.breadcrumb()` | Breadcrumb trail | +| `Terminal.toc()` | Table of contents | + +## Interactive + +| API | Description | +|-----|-------------| +| `Terminal.prompt(String)` | Text input (`.ask()`, `.masked().ask()`) | +| `Terminal.confirm(String)` | Y/n confirmation | +| `Terminal.menu()` | Numbered menu (`.option()`, `.select()`) | +| `Terminal.selectList()` | List with arrow keys + Enter | +| `Terminal.pager()` | Paged output (Enter/arrows/q) | + +## Live / progress + +| API | Description | +|-----|-------------| +| `Terminal.progressBar()` | Progress bar (`.total()`, `.build()`) | +| `Terminal.spinner()` | Spinning indicator (`.message()`, `.start()`) | +| `Terminal.dashboard()` | Refreshing widget panel | + +## Data & visuals + +| API | Description | +|-----|-------------| +| `Terminal.diff()` | Diff view | +| `Terminal.log()` | Log-style output | +| `Terminal.timeline()` | Timeline | +| `Terminal.heatmap()` | Heatmap | +| `Terminal.chart()` | Charts | + +## Other + +| API | Description | +|-----|-------------| +| `Terminal.badge(String, Color)` | Colored badge | +| `Terminal.notify(String, Type)` | Notification (info/success/warning/error) | +| `Terminal.code(String)` | Code block with language | +| `Terminal.sysinfo()` | System info (OS, Java, etc.) | +| `Terminal.markdown(String)` | Render markdown to terminal | + +Use the fluent API from `Terminal.*`. For tests or to disable ANSI, inject a custom `TerminalSupport`. diff --git a/docs/Examples.md b/docs/Examples.md new file mode 100644 index 0000000..652b4ad --- /dev/null +++ b/docs/Examples.md @@ -0,0 +1,262 @@ +# Examples + +All examples use `import dev.jakub.terminal.Terminal;` and `import dev.jakub.terminal.core.Color;` where needed. Use `System.out` or omit the argument where `.print()` has a no-arg overload. + +--- + +## Text & rules + +```java +Terminal.print("Hello").color(Color.CYAN).bold().println(); + +Terminal.rule().character('=').print(); +Terminal.rule().doubles().prefix("-- ").suffix(" --").print(); +``` + +## Key-value & box + +```java +Terminal.keyValue() + .row("Name", "terminal-ui") + .row("Version", "1.0") + .separator(" = ") + .print(System.out); + +Terminal.box() + .title("Info") + .line("First line") + .lines("Second", "Third") + .print(System.out); +``` + +## Table + +```java +Terminal.table() + .header("Col A", "Col B", "Col C") + .row("1", "2", "3") + .row("4", "5", "6") + .print(System.out); +``` + +## Tree + +```java +Terminal.tree() + .node("root") + .child("src") + .child("main").end() + .child("test").end() + .end() + .child("docs") + .end() + .print(System.out); +``` + +## Columns + +```java +Terminal.columns() + .column("Left\ncolumn\ntext") + .column("Middle") + .column("Right") + .print(System.out); +``` + +## Steps (wizard-style) + +```java +Terminal.steps() + .step("Setup", Steps.Status.DONE) + .step("Build", Steps.Status.RUNNING) + .step("Deploy", Steps.Status.PENDING) + .print(System.out); +``` + +(Use `import dev.jakub.terminal.components.Steps;` for `Steps.Status`.) + +## Breadcrumb + +```java +Terminal.breadcrumb() + .crumb("Home") + .crumb("Projects") + .crumb("terminal-ui") + .separator(" / ") + .print(System.out); +``` + +## Interactive: Prompt + +```java +String name = Terminal.prompt("Name: ").ask(); +String secret = Terminal.prompt("Password: ").masked().ask(); +// With shared scanner (e.g. in a loop): +String line = Terminal.prompt("Input: ").ask(sharedScanner); +``` + +## Interactive: Confirm + +```java +boolean yes = Terminal.confirm("Continue?").defaultYes().ask(); +boolean no = Terminal.confirm("Delete?").defaultNo().ask(); +boolean answer = Terminal.confirm("Proceed?").ask(sharedScanner); +``` + +## Interactive: Menu + +```java +String env = Terminal.menu() + .title("Choose environment") + .option("Development") + .option("Staging") + .option("Production") + .select(); +``` + +## Interactive: SelectList (arrows + Enter) + +```java +String choice = Terminal.selectList() + .title("Pick one") + .option("Option A") + .option("Option B") + .option("Option C") + .select(); +``` + +## Interactive: Pager + +```java +Terminal.pager() + .lines("Line 1", "Line 2", "Line 3", "Line 4", "Line 5") + .pageSize(3) + .interactive(); +``` + +## Progress bar + +```java +ProgressBar bar = Terminal.progressBar() + .total(100) + .width(40) + .style(ProgressBar.Style.BLOCK) + .build(); +for (int i = 0; i <= 100; i++) { + bar.update(i); + Thread.sleep(30); +} +``` + +(Use `import dev.jakub.terminal.live.ProgressBar;`.) + +## Spinner + +```java +Spinner spin = Terminal.spinner().message("Loading...").start(); +// ... do work ... +spin.stop(); +``` + +(Use `import dev.jakub.terminal.live.Spinner;`.) + +## Diff + +```java +Terminal.diff() + .before("old line 1\nold line 2") + .after("new line 1\nnew line 2\nnew line 3") + .print(System.out); +``` + +## Log + +```java +Terminal.log() + .info("Started") + .warn("Deprecation notice") + .error("Something failed") + .withTimestamp() + .print(System.out); +``` + +## Timeline + +```java +Terminal.timeline() + .event("2024-01-01", "First release") + .event("2024-06-01", "Added SelectList") + .event("2025-01-01", "GitHub Packages") + .print(System.out); +``` + +## Heatmap + +```java +Terminal.heatmap() + .row("Mon", 10, 20, 5, 30) + .row("Tue", 15, 25, 10, 20) + .row("Wed", 5, 15, 25, 35) + .print(System.out); +``` + +## Chart (sparkline / bar) + +```java +Terminal.chart() + .data(1.0, 2.0, 1.5, 3.0, 2.5) + .height(5) + .print(System.out); +``` + +## Badge & notification + +```java +Terminal.badge("OK", Color.GREEN).println(); +Terminal.badge("WARN", Color.YELLOW).print(System.out); + +Terminal.notify("Done!", Notification.Type.SUCCESS); +Terminal.notify("Warning", Notification.Type.WARNING); +Terminal.notify("Error", Notification.Type.ERROR); +Terminal.notify("Info", Notification.Type.INFO); +``` + +(Use `import dev.jakub.terminal.components.Notification;`.) + +## Code block + +```java +Terminal.code("java") + .line("public static void main(String[] args) {") + .line(" System.out.println(\"Hello\");") + .line("}") + .lineNumbers() + .print(System.out); +``` + +## SysInfo + +```java +Terminal.sysinfo().print(System.out); +``` + +## Markdown + +```java +Terminal.markdown("# Title\n\n**Bold** and *italic*.\n\n- Item 1\n- Item 2\n\n---") + .print(System.out); +``` + +## Table of contents + +```java +Terminal.toc() + .section("Introduction").sub("Overview").sub("Install") + .section("API").sub("Reference") + .section("Examples") + .print(System.out); +``` + +--- + +For more, see the [README](https://github.com/jakubbbdev/terminal-ui#usage-excerpt) and the source. diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..7cf0162 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,25 @@ +# terminal-ui + +Java library for building terminal UIs: tables, rules, colors, prompts, menus, SelectList, pager, and more. Fluent API, ANSI support, testable. + +## Quick links + +- **[Install](Install)** – Gradle / Maven dependency +- **[Components](Components)** – What's in the library +- **[Examples](Examples)** – Code snippets + +## Requirements + +- Java 21 +- Gradle 9.x or Maven (wrapper included in repo) + +## Build from source + +```bash +./gradlew build +./gradlew test +``` + +## License + +MIT – see [LICENSE](https://github.com/jakubbbdev/terminal-ui/blob/master/LICENSE) in the repo. diff --git a/docs/Install.md b/docs/Install.md new file mode 100644 index 0000000..ddaa69a --- /dev/null +++ b/docs/Install.md @@ -0,0 +1,45 @@ +# Install + +Published to [GitHub Packages](https://github.com/jakubbbdev/terminal-ui/packages). Use a [release](https://github.com/jakubbbdev/terminal-ui/releases) version (e.g. `1.0.1`) for `VERSION`. + +## Gradle (Kotlin DSL) + +```kotlin +repositories { + mavenCentral() + maven { url = uri("https://maven.pkg.github.com/jakubbbdev/terminal-ui") } +} +dependencies { + implementation("dev.jakub.terminal:terminal-ui:VERSION") +} +``` + +## Gradle (Groovy) + +```groovy +repositories { + mavenCentral() + maven { url "https://maven.pkg.github.com/jakubbbdev/terminal-ui" } +} +dependencies { + implementation "dev.jakub.terminal:terminal-ui:VERSION" +} +``` + +## Maven + +```xml + + github + https://maven.pkg.github.com/jakubbbdev/terminal-ui + + + dev.jakub.terminal + terminal-ui + VERSION + +``` + +## Auth (if required) + +For public packages, resolution often works without credentials. If your build asks for auth, use a [GitHub PAT](https://github.com/settings/tokens) with `read:packages`: username = your GitHub username, password = token. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..eda6954 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,10 @@ +# terminal-ui + +Java library for terminal UIs: tables, prompts, menus, and more. + +- **[Home](Home)** – overview +- **[Install](Install)** – Gradle / Maven +- **[Components](Components)** – what's in the library +- **[Examples](Examples)** – runnable code snippets + +[GitHub repo](https://github.com/jakubbbdev/terminal-ui) · [Releases](https://github.com/jakubbbdev/terminal-ui/releases) · [Packages](https://github.com/jakubbbdev/terminal-ui/packages)