From 9c528be1fff8d82e4c1674d76fb0eb5dc4de3196 Mon Sep 17 00:00:00 2001 From: Manuel Rodriguez Sabella Date: Wed, 19 Aug 2026 17:45:02 -0300 Subject: [PATCH 1/2] docs: expand README examples gallery and fix package count Adds the tutorial ladder and more of the 34 existing example apps to the README's examples table, adds examples/README.md as a full index, and fixes the Packages table (14 -> 15, missing @termuijs/adapters and termuijs CLI rows). Closes #3508 --- README.md | 28 +++++++++++++-- examples/README.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 examples/README.md diff --git a/README.md b/README.md index 6b1fed264..397b2318d 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,8 @@ render( ## Packages +This README covers setup and the example apps in this repo. Full per-widget API reference — constructor options, props, and hooks — lives in the [Karanjot786/TermUI_Docs](https://github.com/Karanjot786/TermUI_Docs) repo, published at [termui.io](https://www.termui.io). + | Package | What it does | |---------|-------------| | [`@termuijs/core`](./packages/core) | Screen buffer, input parsing, event system, flexbox layout, caps flags, WCAG utilities | @@ -133,7 +135,9 @@ render( | [`@termuijs/data`](./packages/data) | Real-time system data: CPU, memory, disk, network, processes; raw API and reactive hooks | | [`@termuijs/dev-server`](./packages/dev-server) | Hot-reload dev server with graceful restart in under 200ms | | [`@termuijs/quick`](./packages/quick) | Fluent builder API for dashboards in ~20 lines | +| [`@termuijs/adapters`](./packages/adapters) | Adapters for popular CLI libraries (git, execa, chalk) and AI/RAG helpers to integrate with TermUI | | [`create-termui-app`](./packages/create-termui-app) | Project scaffolding CLI | +| [`termuijs`](./packages/cli) | Component-adding CLI — `npx termuijs add ` copies a widget's source into your project | ## Features @@ -428,10 +432,15 @@ cd examples/ai-streaming bun run dev ``` -### Available Examples +### Examples Gallery + +New to TermUI? Start with the tutorial ladder, then explore the rest by topic. | Example | Purpose | Features demonstrated | Path | |---------|---------|-----------------------|------| +| 01 · Hello World | Smallest possible TermUI app | `App`, `Box`, `Text`, `Center`, key event handling | [`examples/01-hello-world`](./examples/01-hello-world) | +| 02 · Simple Button | Focusable, clickable button | Custom `Widget` subclass, focus state, Enter/Space key handling | [`examples/02-simple-button`](./examples/02-simple-button) | +| 03 · Form Inputs | Text input with live display | `TextInput`, `handleKey`, `onSubmit` | [`examples/03-form-inputs`](./examples/03-form-inputs) | | Auth Flow | Demonstrates authentication | Store, Text inputs, conditional rendering | [`examples/auth-flow`](./examples/auth-flow) | | Todo App | Interactive todo list | Store batching, Lists, Inputs | [`examples/todo-app`](./examples/todo-app) | | Forms and Validation | Form validation | Form widget, inputs, modals | [`examples/forms-and-validation`](./examples/forms-and-validation) | @@ -443,6 +452,21 @@ bun run dev | Widget Gallery | All widgets in one place | Comprehensive widget showcase | [`examples/widget-gallery`](./examples/widget-gallery) | | CLI Wrapper | Live log streaming | Subprocesses, streaming output | [`examples/cli-wrapper-live`](./examples/cli-wrapper-live) | | AI Assistant | Interactive AI chat with streaming | ChatMessage, StreamingText, ToolCall, ToolApproval, useAI, dual-mode operation | [`examples/ai-assistant`](./examples/ai-assistant) | +| Chat App | Streaming chat UI | Widget, ScrollView, TextInput | [`examples/chat-app`](./examples/chat-app) | +| Kanban Board | Kanban board | Custom Widget, Box, Text | [`examples/kanban-board`](./examples/kanban-board) | +| REST Client | Postman-style REST client | Form, Tabs, JSONView | [`examples/rest-client`](./examples/rest-client) | +| Log Viewer | Log viewer with realtime logs and filtering | Widget composition, custom header/filter/sidebar components | [`examples/log-viewer`](./examples/log-viewer) | +| Process Monitor | Process monitor using chart widgets and data hooks | JSX runtime, Table, LineChart, BarChart, `@termuijs/data` hooks | [`examples/process-monitor`](./examples/process-monitor) | +| Flashcard App | Flashcard study app | Widget, Box, Text, Center | [`examples/flashcard-app`](./examples/flashcard-app) | +| Quiz App | Multiple-choice quiz app | Widget, Box, Text, Center | [`examples/quiz-app`](./examples/quiz-app) | +| Markdown Viewer | Scrollable terminal markdown reader | Markdown widget, ScrollView, word wrap | [`examples/markdown-viewer`](./examples/markdown-viewer) | +| DB Browser | SQLite database browser | `bun:sqlite`, Tree, Table, ScrollView | [`examples/db-browser`](./examples/db-browser) | +| Git Client | Git client | List, DiffView | [`examples/git-client`](./examples/git-client) | +| File Manager | File manager | DirectoryTree, FilePicker | [`examples/file-manager`](./examples/file-manager) | +| Pomodoro Timer | Pomodoro timer | Widget, Box, Text, Center, `@termuijs/motion` transitions | [`examples/pomodoro-timer`](./examples/pomodoro-timer) | +| Calculator | Calculator | Widget, Box, Text, Grid, Center | [`examples/calculator`](./examples/calculator) | + +See [`examples/`](./examples) for the full list — 34 runnable programs. ## Project structure @@ -482,7 +506,7 @@ examples/ ```bash bun install -bun run build # Build all 14 packages +bun run build # Build all 15 packages bun run test # Run all 5018 tests bun run coverage # Generate test coverage report bun run typecheck # Type-check all packages diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 000000000..821431554 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,87 @@ +# Examples + +Every folder in this directory is a standalone, runnable TermUI app with its own `package.json`. To run one: + +```bash +cd examples/ +bun install +bun run dev # watch mode, or: +bun run start # single run +``` + +Looking for full API docs (props, constructor options) instead of example code? See [termui.io](https://www.termui.io) / [TermUI_Docs](https://github.com/Karanjot786/TermUI_Docs). + +## Getting started + +The tutorial ladder — start here if you're new to TermUI. + +| Example | Purpose | +|---------|---------| +| [`01-hello-world`](./01-hello-world) | Beginner example: basic text display | +| [`02-simple-button`](./02-simple-button) | Beginner example: button with click | +| [`03-form-inputs`](./03-form-inputs) | Beginner example: text input with live display | + +## Dashboards & data + +| Example | Purpose | +|---------|---------| +| [`dashboard`](./dashboard) | Example dashboard app using TermUI | +| [`jsx-dashboard`](./jsx-dashboard) | JSX-based system dashboard — React-like components for the terminal | +| [`system-monitor`](./system-monitor) | System monitor — built with `@termuijs/quick` in ~25 lines | +| [`process-monitor`](./process-monitor) | Process monitor using chart widgets and `@termuijs/data` hooks | +| [`data-grid`](./data-grid) | Sortable, navigable data grid built with the `DataGrid` widget | +| [`weather`](./weather) | Weather dashboard for a given lat/lon, built with the `@termuijs/quick` fluent API | +| [`widget-gallery`](./widget-gallery) | TermUI Widget Gallery — themes, grid, skeleton, notifications | +| [`showcase`](./showcase) / [`ai-streaming`](./ai-streaming) | Showcase apps demonstrating all framework packages | + +## AI & real-time + +| Example | Purpose | +|---------|---------| +| [`ai-assistant`](./ai-assistant) | AI assistant with mock and real modes — `ChatMessage`, `StreamingText`, `ToolCall`, `ToolApproval` | +| [`chat-app`](./chat-app) | Streaming chat UI | +| [`rss-reader`](./rss-reader) | RSS/Atom feed reader that fetches and parses a live feed | +| [`cli-wrapper-live`](./cli-wrapper-live) | Live log streaming from a wrapped CLI subprocess | + +## Productivity & tools + +| Example | Purpose | +|---------|---------| +| [`todo-app`](./todo-app) | Todo app — built with `@termuijs/quick` in ~20 lines | +| [`forms-and-validation`](./forms-and-validation) | Forms and validation example app | +| [`auth-flow`](./auth-flow) | Auth flow example using `@termuijs/store` and TermUI widgets | +| [`kanban-board`](./kanban-board) | Kanban board example app | +| [`pomodoro-timer`](./pomodoro-timer) | Pomodoro timer example app | +| [`flashcard-app`](./flashcard-app) | Flashcard study app — built with `@termuijs/widgets` | +| [`quiz-app`](./quiz-app) | Multiple-choice quiz app — built with `@termuijs/widgets` | +| [`markdown-editor`](./markdown-editor) | Live markdown editor with a side-by-side preview pane | +| [`markdown-viewer`](./markdown-viewer) | Scrollable terminal markdown reader | +| [`json-explorer`](./json-explorer) | Interactive JSON file explorer — file picker plus a collapsible, scrollable JSON tree view | +| [`file-manager`](./file-manager) | File manager example app | +| [`db-browser`](./db-browser) | SQLite database browser | +| [`git-client`](./git-client) | Git client example app | +| [`rest-client`](./rest-client) | Postman-style REST client | +| [`log-viewer`](./log-viewer) | Log viewer with realtime logs and filtering | +| [`calculator`](./calculator) | Calculator example app | + +## Games + +| Example | Purpose | +|---------|---------| +| [`snake-game`](./snake-game) | Classic Snake game rendered in the terminal | + +## Architecture + +| Example | Purpose | +|---------|---------| +| [`multi-screen-router`](./multi-screen-router) | Multi-screen routing with `@termuijs/router` | + +## Standalone demo scripts + +A few single-file demos live at the top level of `examples/` (no `package.json`, no install step) — run them directly from the repo root: + +```bash +bun examples/braille-chart.ts # LineChart + BrailleCanvas rendering +bun examples/demo-animations.ts # Checkbox / Switch animation demo +bun examples/menubar-demo.ts # MenuBar widget demo +``` From 6ea487d778be9be36df9c2bbc2f47cba5740ff8b Mon Sep 17 00:00:00 2001 From: Manuel Rodriguez Sabella Date: Wed, 19 Aug 2026 17:54:10 -0300 Subject: [PATCH 2/2] docs: address CodeRabbit review feedback on examples gallery PR Fix stale TOC anchor (Available Examples -> Examples Gallery), clarify the 34 apps + 3 standalone scripts count, and document that standalone demos need the root bun install/bun run build first. --- README.md | 4 ++-- examples/README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 397b2318d..918ae65e4 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ A powerful TypeScript and JavaScript framework tailored for building rich termin - [Architecture](#architecture) - [Examples](#examples) - [Running the Examples](#running-the-examples) - - [Available Examples](#available-examples) + - [Examples Gallery](#examples-gallery) - [Project Structure](#project-structure) - [Development](#development) - [Requirements](#requirements) @@ -466,7 +466,7 @@ New to TermUI? Start with the tutorial ladder, then explore the rest by topic. | Pomodoro Timer | Pomodoro timer | Widget, Box, Text, Center, `@termuijs/motion` transitions | [`examples/pomodoro-timer`](./examples/pomodoro-timer) | | Calculator | Calculator | Widget, Box, Text, Grid, Center | [`examples/calculator`](./examples/calculator) | -See [`examples/`](./examples) for the full list — 34 runnable programs. +See [`examples/`](./examples) for the full list — 34 example applications plus 3 standalone demo scripts (37 runnable programs). ## Project structure diff --git a/examples/README.md b/examples/README.md index 821431554..8976467bf 100644 --- a/examples/README.md +++ b/examples/README.md @@ -78,7 +78,7 @@ The tutorial ladder — start here if you're new to TermUI. ## Standalone demo scripts -A few single-file demos live at the top level of `examples/` (no `package.json`, no install step) — run them directly from the repo root: +A few single-file demos live at the top level of `examples/` (no `package.json`, no per-demo install step). They import `@termuijs/core`, `@termuijs/widgets`, and `@termuijs/ui` directly, so run the root [`bun install` / `bun run build`](../README.md#running-the-examples) steps first, then run them directly from the repo root: ```bash bun examples/braille-chart.ts # LineChart + BrailleCanvas rendering