termline 1.1.1 → 1.1.3

data/readme.md

@@ -1,55 +1,293 @@
-<div align="center" class="documentation-header">
-    <img width="100" alt="LesliTesting logo" src="./docs/images/termline-logo.svg" />
-    <h3 align="center">Human-friendly terminal logs for the Lesli Platform</h3>
+<div align="center">
+    <h1 align="center">
+        <img width="100" alt="Termline" src="./docs/images/termline-logo.svg" />
+    </h1>
+    <h3 align="center">Human-friendly terminal output for Ruby applications.</h3>
 </div>
 
 <br />
-<hr/>
+
+<div align="center">
+    <a target="_blank" href="https://github.com/LesliTech/Termline/actions/workflows/master.yml">
+        <img alt="Termline test status" src="https://img.shields.io/github/actions/workflow/status/LesliTech/Termline/master.yml?branch=master&style=for-the-badge&logo=github&label=tests">
+    </a>
+    <a target="_blank" href="https://rubygems.org/gems/termline">
+        <img alt="Gem Version" src="https://img.shields.io/gem/v/termline?style=for-the-badge&logo=ruby">
+    </a>
+    <a target="_blank" href="https://codecov.io/github/LesliTech/Termline">
+        <img alt="Codecov" src="https://img.shields.io/codecov/c/github/LesliTech/Termline?style=for-the-badge&logo=codecov">
+    </a>
+    <a target="_blank" href="https://sonarcloud.io/project/overview?id=LesliTech_Termline">
+        <img alt="Sonar Quality Gate" src="https://img.shields.io/sonar/quality_gate/LesliTech_Termline?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge&logo=sonarqubecloud&label=Quality">
+    </a>
+</div>
+
+<br />
+
+<div align="center">
+    <img
+        style="width:100%;max-width:800px;border-radius:6px;"
+        alt="Termline formatted terminal output"
+        src="./docs/images/screenshot.png" />
+</div>
+
+<br />
+
+---
+
+<br />
+
+## Introduction
+
+Termline provides human-friendly terminal output for applications and development tools built with the [Lesli Framework](https://github.com/LesliTech/Lesli).
+
+It exposes a small Ruby API for semantic messages, colors, icons, structured metadata, lists, tables, and separators. Termline has no application-framework dependency, so it can also be used by standalone Ruby applications, scripts, Rake tasks, and command-line tools.
+
 <br />
 
+## Why Termline?
 
-### Quick start
+Termline provides:
+
+- Consistent terminal output across the Lesli ecosystem
+- Semantic info, success, warning, and danger messages
+- Colored icons, labels, and timestamps
+- Structured key-value metadata
+- Ordered and unordered lists
+- Terminal-aware tables with alignment and truncation
+- Reusable titles, detail blocks, spacing, and adaptive separators
+- A lightweight implementation with no runtime dependencies
+
+<br />
+
+## Quick Start
+
+### Requirements
+
+- Ruby 2.7.2 or newer
+
+Termline is framework-independent and does not require Rails.
+
+### Installation
+
+Add Termline to the application:
 
 ```shell
-# Add LesliAdmin engine gem
 bundle add termline
 ```
 
-### Usage 
+Require the gem when Bundler does not load it automatically:
+
+```ruby
+require "termline"
+```
+
+<br />
+
+## Usage
+
+### Messages
+
 ```ruby
+require "termline"
+
 Termline.msg "Hello world"
 Termline.info "Server started"
 Termline.success "All tests passed"
 Termline.warning "Low disk space"
 Termline.danger "Something failed"
+```
 
-Termline.br
+Every semantic helper accepts multiple messages and prints each one on its own line:
+
+```ruby
+Termline.info "Loading configuration", "Connecting to database"
+```
+
+Attach structured metadata with keyword arguments:
+
+```ruby
+Termline.success "Compiled application.tailwind.css", size: "1.4 KB"
+Termline.info "Connected", adapter: "postgres", duration: "12ms"
+```
+
+Metadata is rendered in a compact, readable form such as `adapter=postgres duration=12ms`.
+
+Override the default tag, icon, or timestamp when the output needs a different presentation:
+
+```ruby
+Termline.info "User authenticated", tag: "AUTH:", icon: :star
+Termline.success "Cache warmed", time: false
+```
+
+Timestamp defaults can also be configured once for the application:
+
+```ruby
+Termline.configure do |config|
+  config.timestamps = false
+  config.timestamp_format = "%H:%M:%S"
+end
+```
+
+### Lists and tables
+
+```ruby
+Termline.list("Rails", "Lesli", "Tailwind")
+Termline.list("Database", "Cache", icon: :success, color: :green)
+Termline.ordered_list("Install", "Configure", "Run", start: 1)
 
 Termline.table([
   { name: "Luis", role: "Admin", status: "Active" },
   { name: "Ana", role: "Developer", status: "Pending" }
-])
+], align: { name: :left, status: :center })
 ```
 
-**Result:** 
+Tables fit the available terminal width, truncate long values with `…`, and right-align numeric columns automatically.
+
+### Titles and details
 
-<img  alt="LesliTesting logo" src="./docs/images/screenshot.png" />
+```ruby
+Termline.title "Deployment"
+Termline.details environment: "production", version: "1.4.0"
+Termline.details({ status: "ready", workers: 4 }, icons: { status: :success, workers: :info })
+```
 
+### Spacing and separators
 
-### Documentation
-* [website](https://www.lesli.dev/)
-* [documentation](https://www.lesli.dev/gems/termline/)
+```ruby
+Termline.br
+Termline.br(2)
+Termline.line
+Termline.line(character: "=")
+```
 
+Without arguments, `line` adapts to the current terminal width.
 
-### Connect with Lesli
+### Public API
 
-* [X: @LesliTech](https://x.com/LesliTech)
-* [Email: hello@lesli.tech](hello@lesli.tech)
-* [Website: https://www.lesli.tech](https://www.lesli.tech)
+| Helper | Purpose |
+| --- | --- |
+| `Termline.m` | Print one or more unformatted values |
+| `Termline.msg` | Print neutral messages with optional metadata |
+| `Termline.info` | Print informational messages |
+| `Termline.success` | Print successful outcomes |
+| `Termline.warning` | Print warnings |
+| `Termline.danger` | Print errors or failed outcomes |
+| `Termline.alert` | Print a high-visibility alert |
+| `Termline.deprecation` | Print a deprecation warning |
+| `Termline.list` | Print an unordered styled list |
+| `Termline.ordered_list` | Print a numbered list |
+| `Termline.table` | Print width-aware arrays, hashes, or Active Record relations as a table |
+| `Termline.title` | Print a terminal-width section title |
+| `Termline.details` | Print an aligned block of labeled details |
+| `Termline.br` | Print blank lines |
+| `Termline.line` | Print a visual separator |
+| `Termline.color` | Print a terminal-width background color bar when ANSI is enabled |
+| `Termline.configure` | Configure output, ANSI mode, width, and timestamp defaults |
 
+Message, list, table, and spacing helpers write to the configured output, which defaults to `$stdout`. See the focused guides for all supported options and lower-level builders:
+
+- [Installation](https://www.lesli.dev/gems/termline/about/installation)
+- [Messages](https://www.lesli.dev/gems/termline/messages)
+- [Lists](https://www.lesli.dev/gems/termline/lists)
+- [Tables](https://www.lesli.dev/gems/termline/tables)
+- [Details](https://www.lesli.dev/gems/termline/details)
+- [Titles](https://www.lesli.dev/gems/termline/text)
+- [Separators and spacing](https://www.lesli.dev/gems/termline/separator)
+
+### Output configuration
+
+Termline writes to `$stdout` and enables ANSI styles automatically for interactive terminals. Redirect the output or override ANSI rendering when needed:
+
+```ruby
+require "stringio"
+
+buffer = StringIO.new
+Termline.output = buffer
+Termline.ansi = false
+
+Termline.success "Saved", time: false
+buffer.string # => "✔ SUCCESS: Saved\n"
+```
+
+The supported ANSI modes are `:auto`, `true`, and `false`. Automatic mode disables escape sequences when the output is not a TTY, when `TERM=dumb`, or when the `NO_COLOR` environment variable is present.
+
+The terminal width is detected when content is rendered and falls back to 80 columns. It can be overridden explicitly:
+
+```ruby
+Termline.width = 100
+```
+
+Message timestamps are enabled by default. Use `Termline.timestamps = false` to disable them globally, and `time: true` or `time: false` to override the setting for one message.
+
+<br />
+
+## Development
+
+Clone the repository and install its dependencies:
+
+```shell
+git clone https://github.com/LesliTech/Termline.git
+cd Termline
+bundle install
+```
+
+To use local source from a Lesli development workspace, reference it from the host application's `Gemfile`:
+
+```ruby
+gem "termline", path: "gems/Termline"
+```
+
+### Tests
+
+Run the default test task from the Termline directory:
+
+```shell
+bundle exec rake
+```
+
+The suite uses LesliTesting for the shared Lesli reporter and coverage configuration. Coverage is opt-in:
+
+```shell
+COVERAGE=true bundle exec rake
+```
+
+Use `QUIET=true` to suppress the line printed for every individual test:
+
+```shell
+QUIET=true COVERAGE=true bundle exec rake
+```
+
+Run the executable examples to preview the available output styles:
+
+```shell
+bundle exec ruby test/demo_termline.rb
+```
+
+<br />
+
+## Documentation
+
+- [Lesli website](https://www.lesli.dev/)
+- [Termline documentation](https://www.lesli.dev/gems/termline/)
+- [Testing guide](https://www.lesli.dev/gems/termline/about/testing)
+- [Roadmap and P3 ToDo](./todo.md)
+- [Releases and changelog](https://github.com/LesliTech/Termline/releases)
+- [Issue tracker](https://github.com/LesliTech/Termline/issues)
+- [Source code](https://github.com/LesliTech/Termline)
+
+<br />
+
+## Community
+
+- [X: @LesliTech](https://x.com/LesliTech)
+- [hello@lesli.tech](mailto:hello@lesli.tech)
+- [https://www.lesli.tech](https://www.lesli.tech)
+
+<br />
+
+## License
 
-### License
--------
 Copyright (c) 2026, Lesli Technologies, S. A.
 
 This program is free software: you can redistribute it and/or modify
@@ -63,19 +301,16 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with this program. If not, see http://www.gnu.org/licenses/.
+along with this program. If not, see [https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
 
-<br />
-<hr />
-<br />
-<br />
+The complete license text is available in the [license file](./license.txt).
 
-<div align="center" class="has-text-centered">
-    <img width="200" alt="Lesli logo" src="https://cdn.lesli.tech/lesli/brand/app-logo.svg" />
-    <h3 align="center" class="mt-0">
-        The Open-Source SaaS Development Framework for Ruby on Rails.
-    </h3>
-</div>
+---
 
 <br />
 <br />
+
+<div align="center">
+    <img width="80" alt="Lesli icon" src="https://cdn.lesli.tech/lesli/brand/app-icon.svg" />
+    <h3 align="center">The Open-Source SaaS Development Framework for Ruby on Rails.</h3>
+</div>

data/todo.md

@@ -0,0 +1,52 @@
+# Termline ToDo
+
+## P3 · Advanced terminal components
+
+P3 will extend Termline with richer terminal interfaces while preserving its current lightweight architecture: direct string builders, no markup parser, no component tree, and no runtime dependencies.
+
+### Foundation
+
+- [ ] Add a shared visible-width utility that ignores ANSI escape sequences.
+- [ ] Handle Unicode and wide characters correctly when padding, aligning, and truncating content.
+- [ ] Reuse the width utility in tables, titles, separators, and future components.
+- [ ] Define consistent behavior for terminals that are too narrow to render a component.
+
+### Components
+
+- [ ] Add a `panel` component for bordered text, optional titles, padding, and semantic colors.
+- [ ] Add a progress bar with configurable width, total, current value, label, and percentage.
+- [ ] Add a spinner or status indicator for long-running tasks.
+- [ ] Provide static builders for every component so output can be composed and tested without printing.
+- [ ] Make dynamic components update in place only when the output is an interactive TTY.
+- [ ] Provide readable, non-animated output when ANSI is disabled or output is redirected.
+
+### API and configuration
+
+- [ ] Define a small semantic theme API for message levels and component colors.
+- [ ] Keep public helpers consistent with the existing `Termline.*` API.
+- [ ] Support explicit width overrides without bypassing terminal-width safety.
+- [ ] Validate component options and return actionable `ArgumentError` messages.
+
+### Quality and documentation
+
+- [ ] Add tests for ANSI and plain-text rendering.
+- [ ] Add tests for narrow terminals, redirected output, Unicode content, and interrupted animations.
+- [ ] Add examples to `test/demo_termline.rb`.
+- [ ] Document every new public helper and its builder API.
+- [ ] Update the README screenshot after the P3 components are stable.
+- [ ] Confirm that the final gem still has no runtime dependencies.
+
+### Definition of done
+
+- [ ] All builders return strings without writing directly to the terminal.
+- [ ] Dynamic output degrades cleanly outside a TTY.
+- [ ] Existing P0–P2 APIs remain backward compatible.
+- [ ] The complete test suite passes on every supported Ruby version.
+- [ ] README, focused guides, demo, and packaged gem reflect the final P3 API.
+
+### Out of scope
+
+- HTML- or Tailwind-style markup parsing.
+- A virtual component tree or terminal DOM.
+- Full-screen terminal application management.
+- Required runtime dependencies.

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: termline
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.3
 platform: ruby
 authors:
 - The Lesli Development Team
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies: []
 description: "Termline is a lightweight Ruby gem for printing terminal messages with
   \ncolors, icons, and semantic log levels.\n"
@@ -18,13 +19,18 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/termline.rb
+- lib/termline/details.rb
 - lib/termline/list.rb
 - lib/termline/msg.rb
 - lib/termline/space.rb
 - lib/termline/style.rb
 - lib/termline/table.rb
+- lib/termline/terminal.rb
+- lib/termline/text.rb
 - lib/termline/version.rb
+- license.txt
 - readme.md
+- todo.md
 homepage: https://www.lesli.dev/
 licenses:
 - GPL-3.0-or-later
@@ -34,6 +40,7 @@ metadata:
   source_code_uri: https://github.com/LesliTech/Termline
   bug_tracker_uri: https://github.com/LesliTech/Termline/issues
   documentation_uri: https://www.lesli.dev/gems/termline/
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -41,14 +48,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.5.16
+signing_key:
 specification_version: 4
 summary: Human-friendly terminal logs for the Lesli Platform.
 test_files: []