ratatui_ruby 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fc5e88c5e6146ec1aeae7816aeb8bea73926aaf90d5b2df75fa58d5c6490ab0
-  data.tar.gz: 90ec60b887d797c1cd8b8f06ca41506dbf8a463abc554c20b7caab8ec537b496
+  metadata.gz: 52112877db56e3edf7a4baa4c542b55570e8b1172a172934e229c0730d33ca2c
+  data.tar.gz: 1f46e0c790f33828dba5ed4cfa6ea6d56d5525634cc587d0986005e287c6b876
 SHA512:
-  metadata.gz: 3d6fdbb5c4c2970210f70cb0f16c0f40eca871afd6cc115cc5e744e9b85aed01b2c7209baabbb4b2e7129f6ddf460f1add31a6612070a8ef239fbb1e5e2893bd
-  data.tar.gz: ffef16474856ead4d0754dcd6f26104b795a6c2d8aac962df73d7f6c468d4fc6ad7c769a68bb97c1ad3fecc487973afbb50764c555f0a8385addf14864d5c22c
+  metadata.gz: 5ee6665ca41a8029b67f9d99ac4908ad5ab124cc8d21952d7a42e3eb3bce0dfd2ef77e19b69294a7c5e2bb1a8bb745047a8f7599712e497ba0c66d3e8607e351
+  data.tar.gz: '085180a5bab1b831521750b42398087109129fda7d20fe369b7aa4ff5c746e691e09f82a4251bc62ca964508ed21d9276ace9970ed91fec3fd979923ea2937a5'

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.1.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.7.2.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/AGENTS.md

@@ -27,7 +27,7 @@ Architecture:
 
 ### STRICT REQUIREMENTS
 
-- Every file MUST begin with an SPDX-compliant header. Use `AGPL-3.0-or-later` for code; `CC-BY-SA-4.0` for documentation. `reuse annotate` can help you generate the header.
+- Every file MUST begin with an SPDX-compliant header. Use `AGPL-3.0-or-later` for code; `CC-BY-SA-4.0` for documentation. `reuse annotate` can help you generate the header. **For Ruby files**, wrap SPDX comments in `#--` / `#++` to hide them from RDoc output.
 - Every line of Ruby MUST be covered by tests that would stand up to mutation testing.
   - Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable.
   - For UI widgets, this means using `with_test_terminal` to verify EVERY character of the terminal buffer's content.
@@ -78,6 +78,7 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 
 ### Development Environment
 
+- **Scripting Preference:** Simple `sed` or shell one-liners are fine. When a one-off script grows to multiple lines of logic, prefer a temporary rake task or `ruby -e '...'` over a multi-line shell script in a string. Ruby's `File.read`/`File.write`, `Dir.glob`, and regex handle complex transformations more cleanly.
 
 ### Documentation
 
@@ -101,6 +102,12 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
         - Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful.
         - **DON'T list the files changed or the edits made in the body.** Don't provide a bulleted list of changes. Use prose to explain the problem and the solution.
         - **DON'T use markdown syntax** (no backticks, no bolding, no lists, no links). The commit message must be plain text.
+- **Type conventions by directory:**
+    - `lib/`, `ext/`, `sig/`: Use `feat`, `fix`, `refactor`, `perf` as appropriate.
+    - `bin/`, `tasks/`, `.builds/`, CI/CD: Always `chore` (internal tooling).
+    - `examples/`: Always `docs` (documentation by example).
+    - `test/`: Use `test` for new/changed tests, or match the type of the code being tested.
+    - `doc/`: Always `docs`.
   
 ### 5. Changelog
 

data/CHANGELOG.md

@@ -18,6 +18,26 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.7.2] - 2026-01-04
+
+### Added
+
+- **Tabs `padding_left` and `padding_right`**: Now accept `Integer` (for spaces), `String`, or `Text::Line` for styled padding content. Previously only accepted `Integer`. Passing a `Line` object allows colored or decorated padding.
+
+### Changed
+
+### Fixed
+
+- **Styled Text Parsing**: Fixed multiple widgets incorrectly rendering styled text objects as Ruby inspect strings (e.g., `#<data RatatuiRuby::Text::Span...>`) instead of their styled content:
+  - `Tabs` `divider`: Now correctly renders `Text::Span` objects.
+  - `Table` `highlight_symbol`: Now correctly renders `Text::Span` objects.
+  - `BarChart` `BarGroup` `label`: Now correctly renders `Text::Line` objects.
+  - `Chart` `Axis` `title`: Now correctly renders `Text::Line` objects.
+  - `Chart` `Axis` `labels`: Now correctly renders `Text::Line` objects.
+  - `Chart` `Dataset` `name`: Now correctly renders `Text::Line` objects.
+
+### Removed
+
 ## [0.7.1] - 2026-01-03
 
 ### Added
@@ -368,6 +388,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[0.7.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.2
 [0.7.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.1
 [0.7.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.0
 [0.6.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.6.0

data/README.md

@@ -23,7 +23,7 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 > [!WARNING]
 > **ratatui_ruby** is currently in **BETA**. The API may change between minor versions.
 
-**[Why RatatuiRuby?](./doc/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](./doc/why.md) to CharmRuby, raw Rust, and Go.
+**[Why RatatuiRuby?](./doc/getting_started/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](./doc/getting_started/why.md) to CharmRuby, raw Rust, and Go.
 
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the [`trunk` branch](https://git.sr.ht/~kerrick/ratatui_ruby/tree/trunk) for pre-release updates.
 
@@ -96,7 +96,7 @@ end
 
 ![Hello Ratatui](./doc/images/verify_readme_usage.png)
 
-For a full tutorial, see [the Quickstart](./doc/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/application_architecture.md).
+For a full tutorial, see [the Quickstart](./doc/getting_started/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/concepts/application_architecture.md).
 
 
 ## Features
@@ -118,9 +118,9 @@ Plus: flexible layouts with constraints, full keyboard/mouse/paste/resize events
 
 | Resource | Description |
 |----------|-------------|
-| [Quickstart](./doc/quickstart.md) | Get running in 5 minutes |
-| [Widget Gallery](./doc/quickstart.md#widget-demos) | Every widget with examples |
-| [Application Architecture](./doc/application_architecture.md) | Patterns for scaling your app |
+| [Quickstart](./doc/getting_started/quickstart.md) | Get running in 5 minutes |
+| [Widget Gallery](./doc/getting_started/quickstart.md#widget-demos) | Every widget with examples |
+| [Application Architecture](./doc/concepts/application_architecture.md) | Patterns for scaling your app |
 | [API Reference](./doc/index.md) | Full RDoc documentation |
 | [Wiki](https://man.sr.ht/~kerrick/ratatui_ruby) | Guides and community resources |
 

data/Rakefile

@@ -8,4 +8,4 @@ require "bundler/gem_tasks"
 # Import all tasks from the tasks/ directory
 Dir.glob("tasks/*.rake").each { |r| import r }
 
-task default: %w[sourcehut test lint]
+task default: %w[lint:fix sourcehut test lint]

data/doc/{application_architecture.md → concepts/application_architecture.md}

@@ -52,6 +52,36 @@ ensure
 end
 ```
 
+#### Signal Handling
+
+External processes send signals. Your TUI must handle them gracefully.
+
+**The Problem:** If a signal terminates your process before `restore_terminal` runs, the terminal stays in raw mode. Your shell becomes unusable until you type `reset` and press Enter (the text won't echo, but it works).
+
+**The Solution:** Ruby's default signal handlers work correctly with `ensure` blocks. Most signals unwind the stack, which triggers cleanup.
+
+| Signal | Source | Terminal Restored? |
+|--------|--------|--------------------|
+| SIGTERM | `kill -15` | ✓ Yes — ensure runs |
+| SIGINT | `kill -2` (not Ctrl+C) | ✓ Yes — ensure runs |
+| SIGKILL | `kill -9` | ✗ No — cannot be caught |
+
+> [!IMPORTANT]
+> **Ctrl+C in Raw Mode:** When your app is in raw mode, pressing Ctrl+C does *not* send SIGINT. It's captured as a `:ctrl_c` key event. Handle this in your event loop—don't use `trap("INT")`.
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    # ...
+    event = tui.poll_event
+    break if event == :ctrl_c  # Handle Ctrl+C yourself
+  end
+end
+```
+
+**Recovery:** If a TUI app leaves your terminal broken, run `reset` in the shell to restore normal behavior.
+
+
 ### Stateful Widgets
 
 Most widgets are stateless configuration. You create them, render them, and they are gone. However, the **runtime status** of some widgets (like Lists and Tables) must persist across frames (e.g., scroll offsets or selection).

data/doc/{event_handling.md → concepts/event_handling.md}

@@ -4,7 +4,7 @@ SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Event Handling in RatatuiRuby
+# Event Handling
 
 `ratatui_ruby` provides a rich, object-oriented event system that supports multiple coding styles, from simple boolean predicates to modern Ruby pattern matching.
 

data/doc/contributors/auditing/parity.md

@@ -0,0 +1,233 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Parity Auditing Process
+
+This guide describes the **process** for auditing RatatuiRuby against upstream Rust Ratatui to find API parity gaps of any kind.
+
+## Philosophy
+
+RatatuiRuby should behave identically to Rust Ratatui. When a Rust user can do something with a widget, a Ruby user should be able to do the equivalent. Deviations are bugs.
+
+## The Audit Mindset
+
+### Ask the Right Questions
+
+Every audit begins with a question:
+
+- "Does RatatuiRuby support everything upstream supports for widget X?"
+- "When I pass type Y to parameter Z, does Ruby do what Rust does?"
+- "Are there features in upstream that we haven't exposed at all?"
+
+### Symptoms That Trigger Audits
+
+- **Inspect strings in output** (`#<data RatatuiRuby::...>`) — type conversion failure
+- **Missing methods** — user can't access upstream functionality
+- **Wrong behavior** — code runs but produces different results than Rust
+- **Type mismatches** — Ruby API accepts different types than Rust API
+
+## The Three-Layer Model
+
+Every RatatuiRuby feature has three layers. Gaps can occur at any layer:
+
+```
+┌─────────────────────────────┐
+│  Ruby API (lib/**/*.rb)    │  ← What users see
+├─────────────────────────────┤
+│  Rust Bindings (ext/**/*.rs)│  ← Bridge layer
+├─────────────────────────────┤
+│  Upstream Ratatui          │  ← Source of truth
+└─────────────────────────────┘
+```
+
+### Layer 1: Ruby API Gaps
+Ruby doesn't expose a parameter that upstream supports.
+
+### Layer 2: Binding Gaps  
+Ruby exposes a parameter, but the Rust binding converts it incorrectly.
+
+### Layer 3: Upstream Changes
+New upstream features we haven't implemented yet.
+
+## Audit Process
+
+### 1. Choose an Audit Scope
+
+Define what you're auditing:
+- **Single widget**: All parameters of `Tabs`
+- **Single feature**: All places that accept styled text
+- **Version delta**: Everything new in Ratatui 0.29
+
+### 2. Establish Source of Truth
+
+For any scope, identify the authoritative upstream source:
+- **Method signatures** → Rust source files
+- **Type constraints** → Generic bounds (`Into<Line>`, `&str`, etc.)
+- **Behavior** → Upstream documentation and tests
+
+### 3. Inventory Our Implementation
+
+List everything in our codebase related to the scope:
+- Ruby classes and methods
+- Rust binding functions
+- Conversion/parsing logic
+
+### 4. Compare Systematically
+
+For each item in the upstream source of truth, ask:
+1. Do we expose this at all?
+2. If yes, does our implementation match the type signature?
+3. If yes, does our behavior match?
+
+### 5. Document Findings
+
+For each gap found, record:
+- What the gap is
+- Where it occurs (files, lines)
+- What upstream expects
+- What we currently do
+
+### 6. Fix and Verify
+
+Apply fixes, then verify:
+- Compiles without errors
+- Tests pass
+- Visual/manual verification if applicable
+
+## Verifying Completeness
+
+Finding gaps is not enough. You must verify you've found **all** gaps within your scope.
+
+### The Completeness Mindset
+
+An initial audit pass often finds the obvious issues. But "obvious" means "incomplete." After your first pass, stop and ask:
+
+- Did I search for **every variation** of the pattern I was looking for?
+- Are there **synonyms or related terms** I should also search?
+- Did I check **all code paths**, not just the happy path?
+- Are there **duplicate implementations** (e.g., `render` vs `render_stateful`)?
+
+### Broaden Your Search Terms
+
+Your first search term won't catch everything. For each pattern, think of variations:
+
+| If you searched for... | Also search for... |
+|------------------------|-------------------|
+| `funcall("to_s"` | `String::try_convert` |
+| `Into<Line>` | `Into<Span>`, `Into<Text>` |
+| One widget's file | All widget files |
+| The method you're fixing | Related methods in the same file |
+
+### Work From the Complete List
+
+Don't spot-check. Generate the **complete list** of potential issues, then classify each one:
+
+1. Run a search that catches all possible instances
+2. Count them (e.g., "31 `to_s` call sites")
+3. Review **every single one**, marking each as "gap" or "correct"
+
+Half-measures lead to half-fixes.
+
+### Verify Against Upstream Exhaustively
+
+For type-related gaps, don't just check the methods you already know about. Search upstream for **all uses of the pattern**:
+
+- `grep -rn 'Into<Line' /path/to/ratatui/src/widgets` finds EVERY place upstream accepts `Line`
+- Then verify we handle EACH of those correctly
+
+### Question Your Assumptions
+
+After completing your audit, challenge yourself:
+
+- "Is there anywhere I should look that I haven't?"
+- "Is there any term I should search that I haven't?"
+- "Am I sure I didn't miss anything?"
+
+If you can't answer confidently, keep searching.
+
+### The "One More Pass" Rule
+
+When you think you're done, do one more verification pass with a different approach:
+
+- If you searched our code first, now search upstream first
+- If you searched for method names, now search for type signatures
+- If you audited file-by-file, now audit feature-by-feature
+
+This catches gaps your initial framing missed.
+
+
+## Search Strategies
+
+Different gap types require different search approaches:
+
+### Finding Type Conversion Gaps
+
+Look for places where we convert Ruby objects to simpler types:
+- `funcall("to_s", ...)` — converting to string
+- `String::try_convert(...)` — same
+- `u16::try_convert(...)` — numeric conversion
+
+Then check: does upstream accept richer types?
+
+### Finding Missing Features
+
+Compare file structure:
+- What files/modules exist upstream?
+- What methods exist in each upstream struct?
+- What parameters does each upstream method accept?
+
+### Finding Behavioral Differences
+
+Run equivalent code in both environments and compare output.
+
+## Red Flags in Our Code
+
+When reviewing RatatuiRuby code, these patterns suggest potential gaps:
+
+| Pattern | Potential Gap |
+|---------|---------------|
+| `funcall("to_s", ...)` | Upstream may accept styled types |
+| `usize` or `u16` for padding | Upstream may accept content types |
+| Missing `parse_*` call before using a value | Type not being converted properly |
+| Widget with fewer Ruby methods than Rust methods | Missing functionality |
+| `// TODO` or `// FIXME` comments | Known gaps |
+
+## Upstream Patterns to Watch For
+
+When reading upstream Rust code, these signatures indicate rich type support:
+
+| Rust Signature | Meaning | Ruby Should Accept |
+|----------------|---------|-------------------|
+| `Into<Span<'a>>` | Styled single fragment | `Text::Span` or `String` |
+| `Into<Line<'a>>` | Styled line | `Text::Line`, `Text::Span`, or `String` |
+| `Into<Text<'a>>` | Multi-line styled | `Text::Text`, `Text::Line`, or `String` |
+| `T: AsRef<str>` | Any string-like | `String` (OK) |
+| `&'a str` | String slice | `String` (OK) |
+
+## Keeping Audits Maintainable
+
+### Create Checklists
+
+For each widget or feature area, maintain a checklist of all parameters with their expected types.
+
+### Track Upstream Changes
+
+When upgrading Ratatui versions:
+1. Read the changelog
+2. Search for new `pub fn` in widget files
+3. Audit new functionality before exposing it
+
+### Automate Where Possible
+
+Consider tooling that:
+- Compares upstream method counts to ours
+- Flags new `to_s` calls in code review
+- Tests styled content rendering
+
+## Example Audit Narrative
+
+> "I noticed inspect strings appearing in my tabs. I asked: 'What types does upstream accept for the divider parameter?' I found `Into<Span>`. I then asked: 'What does our binding do?' I found we call `to_s`. Gap identified."
+
+This narrative approach—asking questions, finding answers, comparing—works for any parity issue.

data/doc/contributors/developing_examples.md

@@ -62,7 +62,7 @@ MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME
 
 Example directories **must** follow a prefixing convention to categorize them alphabetically:
 - `app_`: Application showcases (e.g., `app_analytics`). Class name: `AppAnalytics`.
-- `widget_`: Widget-focused demonstrations (e.g., `widget_gauge_demo`). Class name: `WidgetGaugeDemo`.
+- `widget_`: Widget-focused demonstrations (e.g., `widget_gauge`). Class name: `WidgetGaugeDemo`.
 - `verify_`: Documentation verification examples (e.g., `verify_readme_usage`). Class name: `VerifyReadmeUsage`.
 
 The directory and class names must match (snake_case directory maps to PascalCase class).
@@ -254,7 +254,7 @@ def test_initial_render
 end
 ```
 
-Snapshot auto-saved to: `test/examples/widget_foo_demo/snapshots/initial_render.txt`
+Snapshot auto-saved to: `test/examples/widget_foo/snapshots/initial_render.txt`
 
 ### With Normalization (for dynamic content)
 
@@ -320,7 +320,7 @@ Examples must use **realistic, meaningful data**—not dummy placeholder text. T
 
 **For small datasets (< 10 items):**
 Use hardcoded realistic data. Examples:
-- Geographic coordinates with city names (see `widget_map_demo/app.rb`)
+- Geographic coordinates with city names (see `widget_map/app.rb`)
 - Real product names or person names
 - Meaningful status values ("Completed", "Pending", "Failed")
 

data/doc/contributors/v1.0.0_blockers.md

@@ -1668,7 +1668,7 @@ These are v1.0.0 quality improvements that refine the example suite after P0 is
 **Status:** Important for API discoverability — Documentation should link library and examples
 
 RDoc should cross-link between:
-- **Library classes/methods** ↔ **Examples that use them** (See also: examples/widget_foo_demo)
+- **Library classes/methods** ↔ **Examples that use them** (See also: examples/widget_foo)
 - **Primary methods** ↔ **DWIM/TIMTOWTDI aliases** (See also: tui.foo_bar as alias for tui.foo(:bar))
 
 ######  Current Practice
@@ -1685,7 +1685,7 @@ Done for:
 
 ######  Action
 
-1. Add `# See also: examples/widget_foo_demo/app.rb` to class/method RDoc
+1. Add `# See also: examples/widget_foo/app.rb` to class/method RDoc
 2. Link DWIM methods to TIMTOWTDI variants: `# Also available as: tui.constraint_length (DWIM) vs tui.constraint(:length) (TIMTOWTDI)`
 3. Create consistent pattern across all public APIs in `lib/ratatui_ruby/`
 
@@ -1694,7 +1694,7 @@ Done for:
 ```ruby
 #### Renders text with styling.
 #
-#### See also: examples/widget_paragraph_demo/app.rb (basic paragraph rendering)
+#### See also: examples/widget_paragraph/app.rb (basic paragraph rendering)
 class Paragraph < Data.define(...)
   # ...
 end
@@ -1714,16 +1714,16 @@ end
 
 Current `widget_*` examples mostly focus on interactive parameter turning (changing colors, borders, etc.). While useful for API discovery, they don't show *how* to use the widget in a real application logic flow.
 
-######  The Standard: widget_tabs_demo
+######  The Standard: widget_tabs
 
-The `widget_tabs_demo` was enhanced to show **conditional rendering** of content based on the selected tab in git commit `38ceed39a011d557cc66e11a4598d3341dc7a0cc`. It doesn't just highlight the tab; it changes the screen content. This connects the widget (the tabs) to the problem it solves (view segregation).
+The `widget_tabs` was enhanced to show **conditional rendering** of content based on the selected tab in git commit `38ceed39a011d557cc66e11a4598d3341dc7a0cc`. It doesn't just highlight the tab; it changes the screen content. This connects the widget (the tabs) to the problem it solves (view segregation).
 
 ######  Action
 
 Identify other widget examples that could benefit from this "functional context" treatment:
 
--   **widget_popup_demo:** Show a multi-step modal flow (e.g., Confirm -> Success) rather than just a static overlay.
--   **widget_list_demo:** Show a master-detail view where selecting a list item updates a detail pane.
--   **widget_input_demo:** (If created) Show specific validation logic (email vs number).
+-   **widget_popup:** Show a multi-step modal flow (e.g., Confirm -> Success) rather than just a static overlay.
+-   **widget_list:** Show a master-detail view where selecting a list item updates a detail pane.
+-   **widget_input:** (If created) Show specific validation logic (email vs number).
 
 **Goal:** Every widget example should answer "How do I build a feature with this?" not just "What does this parameter do?"

data/doc/{quickstart.md → getting_started/quickstart.md}

@@ -59,7 +59,7 @@ end
 ```
 <!-- SYNC:END -->
 
-[![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)](../examples/verify_quickstart_lifecycle/README.md)
+[![quickstart_lifecycle](../images/verify_quickstart_lifecycle.png)](../../examples/verify_quickstart_lifecycle/README.md)
 
 #### How it works
 
@@ -115,7 +115,7 @@ end
 3.  **Method Shorthand**: The `TUI` object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby.draw(...)`.
 4.  **Pattern Matching for Events**: Use `case...in` with pattern matching for elegant event dispatch. Always include an `else` clause at the end to catch unmatched event types (mouse, resize, paste, focus, etc.), otherwise Ruby raises `NoMatchingPatternError`.
 
-For a deeper dive into the available application architectures (Manual vs Managed), see [Application Architecture](./application_architecture.md).
+For a deeper dive into the available application architectures (Manual vs Managed), see [Application Architecture](../concepts/application_architecture.md).
 
 ### Adding Layouts
 
@@ -185,7 +185,7 @@ end
 3.  **`Frame#render_widget(widget, rect)`**: You pass the specific area (like `top` or `bottom`) to render the widget into that exact region.
 4.  **`tui.text_span` (`RatatuiRuby::Text::Span`)**: Allows for rich styling within a single line of text.
 
-[![quickstart_layout](./images/verify_quickstart_layout.png)](../examples/verify_quickstart_layout/README.md)
+[![quickstart_layout](../images/verify_quickstart_layout.png)](../../examples/verify_quickstart_layout/README.md)
 
 ## Examples
 
@@ -197,32 +197,32 @@ Focused examples for individual widgets. Each demonstrates a single widget and i
 
 | Widget | What it demonstrates |
 |--------|---------------------|
-| [Bar Chart](../examples/widget_barchart_demo/app.rb) | Grouped bars, data visualization, custom bar styling |
-| [Block](../examples/widget_block_demo/app.rb) | Borders, titles, padding, nested widgets |
-| [Box](../examples/widget_box_demo/app.rb) | Block + Paragraph composition, text wrapping |
-| [Calendar](../examples/widget_calendar_demo/app.rb) | Date highlighting, month display, event markers |
-| [Chart](../examples/widget_chart_demo/app.rb) | Line/scatter plots, axes, legends, datasets |
-| [Gauge](../examples/widget_gauge_demo/app.rb) | Progress bars, percentage display, unicode blocks |
+| [Bar Chart](../examples/widget_barchart/app.rb) | Grouped bars, data visualization, custom bar styling |
+| [Block](../examples/widget_block/app.rb) | Borders, titles, padding, nested widgets |
+| [Box](../examples/widget_box/app.rb) | Block + Paragraph composition, text wrapping |
+| [Calendar](../examples/widget_calendar/app.rb) | Date highlighting, month display, event markers |
+| [Chart](../examples/widget_chart/app.rb) | Line/scatter plots, axes, legends, datasets |
+| [Gauge](../examples/widget_gauge/app.rb) | Progress bars, percentage display, unicode blocks |
 | [Layout Split](../examples/widget_layout_split/app.rb) | Constraint types, flex modes, responsive layouts |
-| [Line Gauge](../examples/widget_line_gauge_demo/app.rb) | Horizontal progress, labels, thin-style gauges |
-| [List](../examples/widget_list_demo/app.rb) | Selection, scrolling, highlight styles, rich text items |
-| [Map](../examples/widget_map_demo/app.rb) | Canvas widget, world map rendering, coordinates |
-| [Popup](../examples/widget_popup_demo/app.rb) | Clear widget, modal dialogs, overlay composition |
-| [Ratatui Logo](../examples/widget_ratatui_logo_demo/app.rb) | Decorative branding widget |
-| [Ratatui Mascot](../examples/widget_ratatui_mascot_demo/app.rb) | ASCII art Ferris mascot |
+| [Line Gauge](../examples/widget_line_gauge/app.rb) | Horizontal progress, labels, thin-style gauges |
+| [List](../examples/widget_list/app.rb) | Selection, scrolling, highlight styles, rich text items |
+| [Map](../examples/widget_map/app.rb) | Canvas widget, world map rendering, coordinates |
+| [Popup](../examples/widget_popup/app.rb) | Clear widget, modal dialogs, overlay composition |
+| [Ratatui Logo](../examples/widget_ratatui_logo/app.rb) | Decorative branding widget |
+| [Ratatui Mascot](../examples/widget_ratatui_mascot/app.rb) | ASCII art Ferris mascot |
 | [Rect](../examples/widget_rect/app.rb) | Geometry helpers, area calculations, contains/intersection |
 | [Rich Text](../examples/widget_rich_text/app.rb) | Spans, lines, inline styling, mixed colors |
-| [Scrollbar](../examples/widget_scrollbar_demo/app.rb) | Orientations, thumb/track styling, scroll state |
+| [Scrollbar](../examples/widget_scrollbar/app.rb) | Orientations, thumb/track styling, scroll state |
 | [Scroll Text](../examples/widget_scroll_text/app.rb) | Paragraph scrolling, viewport control, long content |
-| [Sparkline](../examples/widget_sparkline_demo/app.rb) | Mini charts, time series, bar sets |
+| [Sparkline](../examples/widget_sparkline/app.rb) | Mini charts, time series, bar sets |
 | [Style Colors](../examples/widget_style_colors/app.rb) | Named colors, RGB, indexed 256-color palette |
-| [Table](../examples/widget_table_demo/app.rb) | Row selection, column widths, per-cell styling |
-| [Tabs](../examples/widget_tabs_demo/app.rb) | Tab navigation, highlighting, dividers |
+| [Table](../examples/widget_table/app.rb) | Row selection, column widths, per-cell styling |
+| [Tabs](../examples/widget_tabs/app.rb) | Tab navigation, highlighting, dividers |
 | [Text Width](../examples/widget_text_width/app.rb) | Unicode-aware width measurement, CJK support |
-| [Canvas](../examples/widget_canvas_demo/app.rb) | Drawing shapes, markers, custom graphics |
-| [Cell](../examples/widget_cell_demo/app.rb) | Buffer cell inspection, styling attributes |
-| [Center](../examples/widget_center_demo/app.rb) | Centering content, horizontal/vertical alignment |
-| [Overlay](../examples/widget_overlay_demo/app.rb) | Layering widgets, modal backgrounds |
+| [Canvas](../examples/widget_canvas/app.rb) | Drawing shapes, markers, custom graphics |
+| [Cell](../examples/widget_cell/app.rb) | Buffer cell inspection, styling attributes |
+| [Center](../examples/widget_center/app.rb) | Centering content, horizontal/vertical alignment |
+| [Overlay](../examples/widget_overlay/app.rb) | Layering widgets, modal backgrounds |
 | [Custom Render](../examples/widget_render/app.rb) | Low-level Draw API, escape hatch for custom widgets |
 
 ### Sample Applications
@@ -253,8 +253,8 @@ These larger examples combine widgets into complete applications, demonstrating
 
 Now that you've seen what **ratatui_ruby** can do:
 
-- **Deep dive**: Read the [Application Architecture](./application_architecture.md) guide for scaling patterns
-- **Test your TUI**: See the [Testing Guide](./application_testing.md) for snapshot and style assertions
-- **Explore the API**: Browse the [full RDoc documentation](./index.md)
+- **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
+- **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
+- **Explore the API**: Browse the [full RDoc documentation](../index.md)
 - **Learn the philosophy**: Read [Why RatatuiRuby?](./why.md) for comparisons and design decisions
 - **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/{why.md → getting_started/why.md}

@@ -90,4 +90,4 @@ Ready to build?
 
 - [Quickstart Guide](./quickstart.md) — Your first app in 5 minutes
 - [Widget Gallery](./quickstart.md#widget-demos) — See what's possible
-- [Application Architecture](./application_architecture.md) — Patterns for scaling
+- [Application Architecture](../concepts/application_architecture.md) — Patterns for scaling