ratatui_ruby 0.6.0 → 0.7.0

data/sig/ratatui_ruby/tui/widget_factories.rbs

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class TUI
+    module WidgetFactories
+      def block: (**top) -> Widgets::Block
+      def paragraph: (**top) -> Widgets::Paragraph
+      def list: (**top) -> Widgets::List
+      def list_item: (**top) -> Widgets::ListItem
+      def table: (**top) -> Widgets::Table
+      def row: (**top) -> Widgets::Row
+      def table_row: (**top) -> Widgets::Row
+      def table_cell: (**top) -> Widgets::Cell
+      def tabs: (**top) -> Widgets::Tabs
+      def gauge: (**top) -> Widgets::Gauge
+      def line_gauge: (**top) -> Widgets::LineGauge
+      def sparkline: (**top) -> Widgets::Sparkline
+      def bar_chart: (**top) -> Widgets::BarChart
+      def bar: (**top) -> Widgets::BarChart::Bar
+      def bar_group: (**top) -> Widgets::BarChart::BarGroup
+      def bar_chart_bar: (**top) -> Widgets::BarChart::Bar
+      def bar_chart_bar_group: (**top) -> Widgets::BarChart::BarGroup
+      def chart: (**top) -> Widgets::Chart
+      def dataset: (**top) -> Widgets::Dataset
+      def axis: (**top) -> Widgets::Axis
+      def scrollbar: (**top) -> Widgets::Scrollbar
+      def calendar: (**top) -> Widgets::Calendar
+      def canvas: (**top) -> Widgets::Canvas
+      def clear: (**top) -> Widgets::Clear
+      def cursor: (**top) -> Widgets::Cursor
+      def overlay: (**top) -> Widgets::Overlay
+      def center: (**top) -> Widgets::Center
+      def ratatui_logo: (**top) -> Widgets::RatatuiLogo
+      def ratatui_mascot: (**top) -> Widgets::RatatuiMascot
+      def shape_label: (**top) -> Widgets::Shape::Label
+    end
+  end
+end

data/sig/ratatui_ruby/tui.rbs

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Terminal User Interface facade providing a concise DSL for building TUI applications.
+  #
+  # Combines all factory mixins to provide convenient access to widgets, layouts,
+  # styles, and terminal operations without verbose class name qualification.
+  class TUI
+    include Core
+    include LayoutFactories
+    include StyleFactories
+    include WidgetFactories
+    include TextFactories
+    include StateFactories
+    include CanvasFactories
+    include BufferFactories
+  end
+end

data/tasks/autodoc.rake

@@ -3,45 +3,11 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-require_relative "autodoc/inventory"
-require_relative "autodoc/notice"
-require_relative "autodoc/rbs"
-require_relative "autodoc/rdoc"
 require_relative "autodoc/examples"
 
 namespace :autodoc do
   desc "Update all automatically generated documentation"
-  task all: [:rbs, :rdoc, :examples]
-
-  desc "Update all automatically generated RBS signatures"
-  task rbs: ["rbs:session"]
-
-  desc "Update all automatically generated RDoc files"
-  task rdoc: ["rdoc:session"]
-
-  namespace :rbs do
-    desc "Generate RBS for RatatuiRuby::Session"
-    task :session do
-      require_relative "../lib/ratatui_ruby"
-
-      Autodoc::Rbs.new(
-        path: File.expand_path("../sig/ratatui_ruby/session.rbs", __dir__),
-        notice: Autodoc::Notice.new("autodoc:rbs:session")
-      ).write(Autodoc::Inventory.new)
-    end
-  end
-
-  namespace :rdoc do
-    desc "Generate RDoc autodoc for RatatuiRuby::Session"
-    task :session do
-      require_relative "../lib/ratatui_ruby"
-
-      Autodoc::Rdoc.new(
-        path: File.expand_path("../lib/ratatui_ruby/session/autodoc.rb", __dir__),
-        notice: Autodoc::Notice.new("autodoc:rdoc:session")
-      ).write(Autodoc::Inventory.new)
-    end
-  end
+  task all: [:examples]
 
   desc "Sync code snippets in example READMEs with source files"
   task :examples do

data/tasks/sourcehut.rake

@@ -65,7 +65,10 @@ namespace :sourcehut do
     # This renders a commit SHA that can be pushed to a branch head
     commit_sha = `git rev-parse #{tag_name}^{}`.strip
 
-    # Push the commit to stable branch
+    # Update local stable branch to match
+    sh "git branch -f stable #{commit_sha}"
+
+    # Push the commit to remote stable branch
     # This creates 'stable' if it doesn't exist, or fast-forwards it.
     sh "git push origin #{commit_sha}:stable"
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Kerrick Long
@@ -107,24 +107,21 @@ files:
 - Rakefile
 - doc/application_architecture.md
 - doc/application_testing.md
+- doc/contributors/architectural_overhaul/chat_conversations.md
+- doc/contributors/architectural_overhaul/implementation_plan.md
+- doc/contributors/architectural_overhaul/task.md
 - doc/contributors/design.md
 - doc/contributors/design/ruby_frontend.md
 - doc/contributors/design/rust_backend.md
 - doc/contributors/developing_examples.md
 - doc/contributors/documentation_style.md
-- doc/contributors/dwim_dx.md
-- doc/contributors/examples_audit.md
-- doc/contributors/examples_audit/p1_high.md
-- doc/contributors/examples_audit/p2_moderate.md
 - doc/contributors/index.md
+- doc/contributors/v1.0.0_blockers.md
 - doc/custom.css
 - doc/event_handling.md
 - doc/images/app_all_events.png
-- doc/images/app_analytics.png
 - doc/images/app_color_picker.png
-- doc/images/app_custom_widget.png
 - doc/images/app_login_form.png
-- doc/images/app_mouse_events.png
 - doc/images/app_stateful_interaction.png
 - doc/images/verify_quickstart_dsl.png
 - doc/images/verify_quickstart_layout.png
@@ -155,13 +152,14 @@ files:
 - doc/images/widget_sparkline_demo.png
 - doc/images/widget_style_colors.png
 - doc/images/widget_table_demo.png
-- doc/images/widget_table_flex.png
 - doc/images/widget_tabs_demo.png
 - doc/images/widget_text_width.png
 - doc/index.md
 - doc/interactive_design.md
 - doc/quickstart.md
 - doc/terminal_limitations.md
+- doc/v0.7.0_migration.md
+- doc/why.md
 - examples/app_all_events/README.md
 - examples/app_all_events/app.rb
 - examples/app_all_events/model/app_model.rb
@@ -226,6 +224,7 @@ files:
 - examples/widget_list_demo/app.rb
 - examples/widget_map_demo/README.md
 - examples/widget_map_demo/app.rb
+- examples/widget_overlay_demo/README.md
 - examples/widget_overlay_demo/app.rb
 - examples/widget_popup_demo/README.md
 - examples/widget_popup_demo/app.rb
@@ -293,6 +292,8 @@ files:
 - ext/ratatui_ruby/src/widgets/table_state.rs
 - ext/ratatui_ruby/src/widgets/tabs.rs
 - lib/ratatui_ruby.rb
+- lib/ratatui_ruby/buffer.rb
+- lib/ratatui_ruby/buffer/cell.rb
 - lib/ratatui_ruby/cell.rb
 - lib/ratatui_ruby/event.rb
 - lib/ratatui_ruby/event/focus_gained.rb
@@ -308,6 +309,10 @@ files:
 - lib/ratatui_ruby/event/paste.rb
 - lib/ratatui_ruby/event/resize.rb
 - lib/ratatui_ruby/frame.rb
+- lib/ratatui_ruby/layout.rb
+- lib/ratatui_ruby/layout/constraint.rb
+- lib/ratatui_ruby/layout/layout.rb
+- lib/ratatui_ruby/layout/rect.rb
 - lib/ratatui_ruby/list_state.rb
 - lib/ratatui_ruby/schema/bar_chart.rb
 - lib/ratatui_ruby/schema/bar_chart/bar.rb
@@ -331,6 +336,7 @@ files:
 - lib/ratatui_ruby/schema/ratatui_logo.rb
 - lib/ratatui_ruby/schema/ratatui_mascot.rb
 - lib/ratatui_ruby/schema/rect.rb
+- lib/ratatui_ruby/schema/row.rb
 - lib/ratatui_ruby/schema/scrollbar.rb
 - lib/ratatui_ruby/schema/shape/label.rb
 - lib/ratatui_ruby/schema/sparkline.rb
@@ -339,8 +345,8 @@ files:
 - lib/ratatui_ruby/schema/tabs.rb
 - lib/ratatui_ruby/schema/text.rb
 - lib/ratatui_ruby/scrollbar_state.rb
-- lib/ratatui_ruby/session.rb
-- lib/ratatui_ruby/session/autodoc.rb
+- lib/ratatui_ruby/style.rb
+- lib/ratatui_ruby/style/style.rb
 - lib/ratatui_ruby/table_state.rb
 - lib/ratatui_ruby/test_helper.rb
 - lib/ratatui_ruby/test_helper/event_injection.rb
@@ -348,7 +354,42 @@ files:
 - lib/ratatui_ruby/test_helper/style_assertions.rb
 - lib/ratatui_ruby/test_helper/terminal.rb
 - lib/ratatui_ruby/test_helper/test_doubles.rb
+- lib/ratatui_ruby/tui.rb
+- lib/ratatui_ruby/tui/buffer_factories.rb
+- lib/ratatui_ruby/tui/canvas_factories.rb
+- lib/ratatui_ruby/tui/core.rb
+- lib/ratatui_ruby/tui/layout_factories.rb
+- lib/ratatui_ruby/tui/state_factories.rb
+- lib/ratatui_ruby/tui/style_factories.rb
+- lib/ratatui_ruby/tui/text_factories.rb
+- lib/ratatui_ruby/tui/widget_factories.rb
 - lib/ratatui_ruby/version.rb
+- lib/ratatui_ruby/widgets.rb
+- lib/ratatui_ruby/widgets/bar_chart.rb
+- lib/ratatui_ruby/widgets/bar_chart/bar.rb
+- lib/ratatui_ruby/widgets/bar_chart/bar_group.rb
+- lib/ratatui_ruby/widgets/block.rb
+- lib/ratatui_ruby/widgets/calendar.rb
+- lib/ratatui_ruby/widgets/canvas.rb
+- lib/ratatui_ruby/widgets/cell.rb
+- lib/ratatui_ruby/widgets/center.rb
+- lib/ratatui_ruby/widgets/chart.rb
+- lib/ratatui_ruby/widgets/clear.rb
+- lib/ratatui_ruby/widgets/cursor.rb
+- lib/ratatui_ruby/widgets/gauge.rb
+- lib/ratatui_ruby/widgets/line_gauge.rb
+- lib/ratatui_ruby/widgets/list.rb
+- lib/ratatui_ruby/widgets/list_item.rb
+- lib/ratatui_ruby/widgets/overlay.rb
+- lib/ratatui_ruby/widgets/paragraph.rb
+- lib/ratatui_ruby/widgets/ratatui_logo.rb
+- lib/ratatui_ruby/widgets/ratatui_mascot.rb
+- lib/ratatui_ruby/widgets/row.rb
+- lib/ratatui_ruby/widgets/scrollbar.rb
+- lib/ratatui_ruby/widgets/shape/label.rb
+- lib/ratatui_ruby/widgets/sparkline.rb
+- lib/ratatui_ruby/widgets/table.rb
+- lib/ratatui_ruby/widgets/tabs.rb
 - mise.toml
 - sig/examples/app_all_events/app.rbs
 - sig/examples/app_all_events/model/event_entry.rbs
@@ -414,6 +455,7 @@ files:
 - sig/ratatui_ruby/schema/ratatui_logo.rbs
 - sig/ratatui_ruby/schema/ratatui_mascot.rbs
 - sig/ratatui_ruby/schema/rect.rbs
+- sig/ratatui_ruby/schema/row.rbs
 - sig/ratatui_ruby/schema/scrollbar.rbs
 - sig/ratatui_ruby/schema/sparkline.rbs
 - sig/ratatui_ruby/schema/style.rbs
@@ -429,15 +471,20 @@ files:
 - sig/ratatui_ruby/test_helper/style_assertions.rbs
 - sig/ratatui_ruby/test_helper/terminal.rbs
 - sig/ratatui_ruby/test_helper/test_doubles.rbs
+- sig/ratatui_ruby/tui.rbs
+- sig/ratatui_ruby/tui/buffer_factories.rbs
+- sig/ratatui_ruby/tui/canvas_factories.rbs
+- sig/ratatui_ruby/tui/core.rbs
+- sig/ratatui_ruby/tui/layout_factories.rbs
+- sig/ratatui_ruby/tui/state_factories.rbs
+- sig/ratatui_ruby/tui/style_factories.rbs
+- sig/ratatui_ruby/tui/text_factories.rbs
+- sig/ratatui_ruby/tui/widget_factories.rbs
 - sig/ratatui_ruby/version.rbs
 - tasks/autodoc.rake
 - tasks/autodoc/examples.rb
-- tasks/autodoc/inventory.rb
 - tasks/autodoc/member.rb
 - tasks/autodoc/name.rb
-- tasks/autodoc/notice.rb
-- tasks/autodoc/rbs.rb
-- tasks/autodoc/rdoc.rb
 - tasks/bump.rake
 - tasks/bump/cargo_lockfile.rb
 - tasks/bump/changelog.rb

data/doc/contributors/dwim_dx.md

@@ -1,366 +0,0 @@
-<!-- SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com> -->
-<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
-
-# DWIM / DX Improvements for Application Developers
-
-## Problem Statement
-
-Ruby's philosophy of "Do What I Mean" (DWIM) and human-centric design should extend to ratatui_ruby's API. Currently, app developers encounter friction points that force them to remember non-obvious conventions, use overly verbose code, or pattern-match when simple predicates would suffice.
-
-This proposal identifies DX issues across the widget API and suggests improvements that maintain backward compatibility while providing ergonomic alternatives.
-
-## DX Issues Identified
-
-### 1. Confusing Event Method Names
-
-**Current problem**: `event.char` doesn't exist, but `event.code` returns things like `"enter"`, `"ctrl"`, not just characters.
-
-**What users expect**: 
-- `event.char` should return the printable character (matching the name)
-- `event.ctrl_c?`, `event.enter?`, etc. should work for all key combinations
-- `event.key?`, `event.mouse?` predicates exist but only for broad categories
-
-**Solution implemented**: Added `char` method and dynamic predicates via `method_missing`. See `lib/ratatui_ruby/event/key.rb`.
-
-### 2. Dual Parameter APIs Without Predicates
-
-**Current problem**: Widgets accept both forms but no convenience methods to query the state:
-
-```ruby
-# Both work, but which one does the widget store?
-gauge1 = Gauge.new(ratio: 0.75)
-gauge2 = Gauge.new(percent: 75)
-gauge1.ratio  # Works
-gauge1.percent  # Does NOT exist
-```
-
-Similarly with List and Table:
-```ruby
-list.selected_index = 2  # Works
-list.selected?  # Does NOT exist
-list.is_selected?  # Does NOT exist
-```
-
-**Affected widgets**: 
-- `Gauge` (ratio vs percent)
-- `LineGauge` (ratio vs percent)
-- `List` (selected_index with no query methods)
-- `Table` (selected_row and selected_column with no query methods)
-
-**Suggested solutions**:
-
-For `Gauge` and `LineGauge`:
-```ruby
-# Add convenience predicates
-gauge.percent  # => 75 (coerced from ratio internally)
-gauge.percent = 50  # => Updates ratio to 0.5
-
-# Or provide explicit accessors
-gauge.as_percent  # => 75
-gauge.as_ratio   # => 0.75
-```
-
-For `List` and `Table`:
-```ruby
-list.selected?  # => true if selected_index is not nil
-list.selection  # => 2 (alias for selected_index)
-list.selected_item  # => "Item 3"
-
-table.selected_row?  # => true if selected_row is not nil
-table.selected_cell?  # => true if both row and column selected
-```
-
-### 3. Symbol Constants for Enum Values
-
-**Current problem**: Magic symbol values scattered across code:
-
-```ruby
-list = List.new(
-  highlight_spacing: :when_selected,  # What are the other options?
-  direction: :top_to_bottom,          # Is :bottom_to_top valid?
-)
-
-layout = Layout.new(
-  flex: :legacy  # What does "legacy" mean?
-)
-
-gauge = Gauge.new(
-  use_unicode: true  # Unclear what ASCII fallback looks like
-)
-```
-
-Users must consult docs or source code to discover valid options.
-
-**Suggested solution**: Add constants to widget classes:
-
-```ruby
-class List < Data
-  # Highlight spacing modes
-  HIGHLIGHT_ALWAYS = :always
-  HIGHLIGHT_WHEN_SELECTED = :when_selected
-  HIGHLIGHT_NEVER = :never
-
-  # Direction modes
-  DIRECTION_TOP_TO_BOTTOM = :top_to_bottom
-  DIRECTION_BOTTOM_TO_TOP = :bottom_to_top
-end
-
-list = List.new(
-  highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED,
-  direction: List::DIRECTION_TOP_TO_BOTTOM,
-)
-```
-
-Benefits:
-- IDE autocomplete shows valid options
-- Self-documenting code
-- Typos caught at runtime (symbol vs constant)
-- Easy to grep for where these modes are used
-
-Affected widgets and their enum values:
-- `List`: `highlight_spacing` (:always, :when_selected, :never), `direction` (:top_to_bottom, :bottom_to_top)
-- `Table`: `highlight_spacing` (same as List), `flex` (:legacy, :default, :fill)
-- `Layout`: `direction` (:vertical, :horizontal), `flex` (:legacy, :default, :fill)
-- `Gauge`/`LineGauge`: `use_unicode` (boolean, but could have MODE_UNICODE, MODE_ASCII)
-- `Paragraph`: `alignment` (:left, :center, :right)
-- `Block`: `border_type` (:plain, :rounded, :double, :thick)
-- `Canvas`: `marker` (:braille, :dots, :half_block, :sextant, :octant)
-
-### 4. Inconsistent Style APIs
-
-**Current problem**: Different widgets accept styles differently:
-
-```ruby
-# Table accepts both
-table = Table.new(style: Style.new(fg: :blue))
-table = Table.new(style: { fg: :blue })  # Hash shorthand
-
-# But Paragraph doesn't
-paragraph = Paragraph.new(text: "hi", style: Style.new(fg: :blue))
-paragraph = Paragraph.new(text: "hi", style: { fg: :blue })  # Works but undocumented
-
-# And Gauge has separate properties
-gauge = Gauge.new(style: Style.new(fg: :blue), gauge_style: Style.new(fg: :green))
-```
-
-**Suggested solution**: Standardize style handling across all widgets:
-
-1. All widgets should accept `Style` objects and `Hash` shorthand
-2. Document this clearly in each widget
-3. Add a convenience constructor:
-
-```ruby
-class Style
-  def self.with(fg: nil, bg: nil, modifiers: [])
-    Style.new(fg: fg, bg: bg, modifiers: modifiers)
-  end
-end
-
-# Cleaner than always spelling out keyword args
-paragraph = Paragraph.new(text: "hi", style: Style.with(fg: :blue))
-```
-
-### 5. Missing State Query Predicates
-
-**Current problem**: Widgets store state but provide no query methods:
-
-```ruby
-list.selected_index = 0
-
-# To check if something is selected, must do:
-if list.selected_index&.nonzero?  # Awkward
-if list.selected_index.nil? == false  # Confusing
-
-# Should be:
-list.selected?  # => true
-list.empty?  # => false (for items array)
-```
-
-**Suggested solution**: Add predicates to state-holding widgets:
-
-```ruby
-# List
-list.selected?      # => !selected_index.nil?
-list.empty?         # => items.empty?
-list.selection      # => selected_index (alias)
-list.selected_item  # => items[selected_index] (convenience)
-
-# Table
-table.selected_row?    # => !selected_row.nil?
-table.selected_cell?   # => !selected_row.nil? && !selected_column.nil?
-table.empty?           # => rows.empty?
-
-# Gauge
-gauge.filled?          # => ratio > 0
-gauge.complete?        # => ratio >= 1.0
-```
-
-### 6. Magic Numeric Coercions
-
-**Current problem**: Widgets accept `Numeric` but silently coerce:
-
-```ruby
-# These all work, but behavior is undocumented
-list = List.new(selected_index: "2")    # Coerced to 2
-list = List.new(selected_index: 2.7)    # Coerced to 2
-list = List.new(selected_index: 2.0)    # Coerced to 2
-
-gauge = Gauge.new(percent: 150)  # Should clamp?
-gauge = Gauge.new(ratio: 1.5)    # Should clamp?
-```
-
-**Suggested solution**: 
-
-1. Document coercion rules explicitly in RDoc
-2. Add validation and raise on invalid inputs:
-
-```ruby
-def initialize(percent: nil, ...)
-  if percent
-    raise ArgumentError, "percent must be 0..100, got #{percent}" unless percent.between?(0, 100)
-    ratio = Float(percent) / 100.0
-  end
-end
-```
-
-3. Provide clear error messages:
-```ruby
-gauge = Gauge.new(percent: 150)
-# => ArgumentError: percent must be between 0 and 100 (got 150)
-```
-
-## Implementation Strategy
-
-### Phase 1: Event Improvements (DONE)
-- [x] Add `char` method to Key event
-- [x] Implement dynamic predicates via `method_missing`
-- [x] Update examples to use new API
-
-### Phase 2: State Query Predicates
-- [ ] Add predicates to `List` (selected?, empty?, selected_item)
-- [ ] Add predicates to `Table` (selected_row?, selected_cell?, empty?)
-- [ ] Add predicates to `Gauge` (filled?, complete?)
-- [ ] Tests for all new predicates
-
-### Phase 3: Symbol Constants
-- [ ] Add enum constants to `List`, `Table`, `Layout`
-- [ ] Add enum constants to `Gauge`, `LineGauge`, `Paragraph`, `Block`
-- [ ] Update all examples to use constants
-- [ ] Document constants in RDoc
-
-### Phase 4: Style Consistency
-- [ ] Standardize `Hash` shorthand support across all widgets
-- [ ] Add `Style.with(fg:, bg:, modifiers:)` convenience constructor
-- [ ] Update `.rbs` files to reflect HashStyle support
-- [ ] Document in style guide
-
-### Phase 5: Numeric Coercion Validation
-- [ ] Add validation to `Gauge`, `LineGauge`, `List`, `Table`
-- [ ] Raise `ArgumentError` on out-of-range values
-- [ ] Provide clear error messages
-- [ ] Update tests
-
-### Phase 6: Convenience Accessors
-- [ ] Add `percent` to `Gauge` and `LineGauge`
-- [ ] Add `selection` alias to `List` and `Table`
-- [ ] Add `selected_item` to `List`
-- [ ] Tests and documentation
-
-## Example: Before and After
-
-### Before (Confusing)
-```ruby
-class GameApp
-  def initialize
-    @menu = List.new(
-      items: ["Start Game", "Load Game", "Options", "Quit"],
-      selected_index: 0,
-      highlight_spacing: :when_selected,  # What's valid here?
-      direction: :top_to_bottom
-    )
-  end
-
-  def handle_input(event)
-    case event
-    when :ctrl_c
-      exit
-    when :up
-      if @menu.selected_index && @menu.selected_index > 0
-        @menu = @menu.with(selected_index: @menu.selected_index - 1)
-      end
-    end
-  end
-
-  def render(tui)
-    tui.draw(@menu)
-  end
-end
-```
-
-### After (DWIM)
-```ruby
-class GameApp
-  def initialize
-    @menu = List.new(
-      items: ["Start Game", "Load Game", "Options", "Quit"],
-      selected_index: 0,
-      highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED,  # IDE autocomplete!
-      direction: List::DIRECTION_TOP_TO_BOTTOM
-    )
-  end
-
-  def handle_input(event)
-    return if event.ctrl_c?  # Dynamic predicate!
-    
-    if event.up?
-      move_menu_up if @menu.selected?  # State predicate!
-    end
-  end
-
-  def move_menu_up
-    index = @menu.selected_index
-    return if index == 0
-    @menu = @menu.with(selected_index: index - 1)
-  end
-
-  def render(tui)
-    tui.draw(@menu)
-  end
-end
-```
-
-## Migration Path
-
-All changes are backward compatible (additive):
-- Existing code using symbols continues to work
-- New constants coexist with symbols
-- New predicates don't change existing behavior
-- New methods are additions, not replacements
-
-Apps can migrate at their own pace:
-```ruby
-# Old style still works
-list = List.new(highlight_spacing: :when_selected)
-
-# New style also works
-list = List.new(highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED)
-
-# Mix and match
-if list.selected?  # New predicate
-  puts list.selected_index  # Old accessor
-end
-```
-
-## Metrics for Success
-
-1. **Discoverability**: New developers can find valid options via IDE autocomplete
-2. **Clarity**: Code self-documents valid states and modes
-3. **Type safety**: Constants and predicates provide type checking
-4. **Error feedback**: Invalid inputs raise with helpful messages
-5. **Backward compatibility**: Zero breaking changes, all existing code works
-
-## Related Issues
-
-- AGENTS.md requirement: All examples must have tests verifying behavior
-- Example improvements: Apply constants and predicates to all example code
-- Documentation: Update style guide with DWIM principles

data/doc/contributors/examples_audit/p1_high.md

@@ -1,21 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Priority 1: High (Polish & Ecosystem)
-
-Important for v1.0.0 quality and ecosystem goals. Not blocking release, but recommended before ship.
-
----
-
-## 1. Ensure All Widgets Have Examples
-
-**Status:** Done
-
-Verified that all widget types shipped with ratatui_ruby have at least one example showing how to use them.
-
-**Action:**
-- [x] Check widget manifest against example inventory
-- [x] Create `widget_canvas_demo`, `widget_center_demo`, and `widget_overlay_demo`
-