ratatui_ruby 0.4.0 → 0.6.0

data/examples/widget_line_gauge_demo/app.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Demonstrates compact status visualization with interactive attribute cycling.
+#
+# Screen space is precious. Standard block gauges are bulky and consume multiple rows.
+#
+# This demo showcases the <tt>LineGauge</tt> widget. It provides an interactive playground where you can cycle through different ratios, symbols, and styling for both filled and unfilled portions in real-time.
+#
+# Use it to understand how to provide status feedback in constrained layouts without consuming vertical space.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_line_gauge_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_line_gauge_demo.png
+class WidgetLineGaugeDemo
+  def initialize
+    @ratio = 0.5
+    @ratios = [0.2, 0.35, 0.5, 0.65, 0.8, 0.95]
+    @ratio_index = 2
+
+    @filled_symbols = [
+      { name: "█ (Block)", symbol: "█" },
+      { name: "▓ (Dark Shade)", symbol: "▓" },
+      { name: "▒ (Medium Shade)", symbol: "▒" },
+      { name: "= (Equals)", symbol: "=" },
+      { name: "# (Hash)", symbol: "#" },
+    ]
+    @filled_symbol_index = 0
+
+    @unfilled_symbols = [
+      { name: "░ (Light Shade)", symbol: "░" },
+      { name: "· (Dot)", symbol: "·" },
+      { name: "- (Dash)", symbol: "-" },
+      { name: "~ (Tilde)", symbol: "~" },
+    ]
+    @unfilled_symbol_index = 0
+
+    @filled_colors = [
+      { name: "Red", color: :red },
+      { name: "Yellow", color: :yellow },
+      { name: "Green", color: :green },
+      { name: "Cyan", color: :cyan },
+      { name: "Blue", color: :blue },
+    ]
+    @filled_color_index = 2
+
+    @unfilled_colors = [
+      { name: "Default", color: nil },
+      { name: "Dark Gray", color: :dark_gray },
+      { name: "Gray", color: :gray },
+    ]
+    @unfilled_color_index = 1
+
+    @base_styles = nil # Initialized in run when @tui is available
+    @base_style_index = 0
+    @hotkey_style = nil # Initialized in run when @tui is available
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+
+      # Initialize styles using tui helpers
+      @base_styles = [
+        { name: "None", style: nil },
+        { name: "Bold White", style: tui.style(fg: :white, modifiers: [:bold]) },
+        { name: "White on Blue", style: tui.style(fg: :white, bg: :blue) },
+        { name: "Italic Cyan", style: tui.style(fg: :cyan, modifiers: [:italic]) },
+      ]
+      @hotkey_style = tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render
+    @ratio = @ratios[@ratio_index]
+
+    filled_color = @filled_colors[@filled_color_index][:color]
+    unfilled_color = @unfilled_colors[@unfilled_color_index][:color]
+
+    filled_style = filled_color ? @tui.style(fg: filled_color) : @tui.style(fg: :white)
+    unfilled_style = unfilled_color ? @tui.style(fg: unfilled_color) : @tui.style(fg: :dark_gray)
+
+    @tui.draw do |frame|
+      # Split into main content and control panel
+      main_area, controls_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(5),
+        ]
+      )
+
+      # Split main area into title, gauges, and spacer
+      title_area, gauge1_area, gauge2_area, spacer_area = @tui.layout_split(
+        main_area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(1),
+          @tui.constraint_length(4),
+          @tui.constraint_length(4),
+          @tui.constraint_fill(1),
+        ]
+      )
+
+      # Render title
+      title = @tui.paragraph(text: "LineGauge Widget Demo - Cycle attributes with hotkeys")
+      frame.render_widget(title, title_area)
+
+      # Example 1: Static gauge showing all features
+      gauge1 = @tui.line_gauge(
+        ratio: @ratio,
+        label: "#{(@ratio * 100).to_i}%",
+        style: @base_styles[@base_style_index][:style],
+        filled_style:,
+        unfilled_style:,
+        filled_symbol: @filled_symbols[@filled_symbol_index][:symbol],
+        unfilled_symbol: @unfilled_symbols[@unfilled_symbol_index][:symbol],
+        block: @tui.block(title: "Interactive Gauge")
+      )
+      frame.render_widget(gauge1, gauge1_area)
+
+      # Example 2: Inverted colors for contrast demonstration
+      gauge2 = @tui.line_gauge(
+        ratio: 1.0 - @ratio,
+        label: "#{((1.0 - @ratio) * 100).to_i}%",
+        filled_style: @tui.style(fg: :black, bg: :yellow),
+        unfilled_style: @tui.style(fg: :white, bg: :dark_gray),
+        filled_symbol: @filled_symbols[@filled_symbol_index][:symbol],
+        unfilled_symbol: @unfilled_symbols[@unfilled_symbol_index][:symbol],
+        block: @tui.block(title: "Inverse (100% - ratio)")
+      )
+      frame.render_widget(gauge2, gauge2_area)
+
+      # Render empty spacer
+      spacer = @tui.paragraph(text: "")
+      frame.render_widget(spacer, spacer_area)
+
+      # Bottom control panel
+      controls = @tui.block(
+        title: "Controls",
+        borders: [:all],
+        children: [
+          @tui.paragraph(
+            text: [
+              # Line 1: General
+              @tui.text_line(spans: [
+                @tui.text_span(content: "←/→", style: @hotkey_style),
+                @tui.text_span(content: ": Ratio (#{(@ratio * 100).to_i}%)  "),
+                @tui.text_span(content: "b", style: @hotkey_style),
+                @tui.text_span(content: ": Base Style (#{@base_styles[@base_style_index][:name]})  "),
+                @tui.text_span(content: "q", style: @hotkey_style),
+                @tui.text_span(content: ": Quit"),
+              ]),
+              # Line 2: Filled
+              @tui.text_line(spans: [
+                @tui.text_span(content: "f", style: @hotkey_style),
+                @tui.text_span(content: ": Filled Symbol (#{@filled_symbols[@filled_symbol_index][:name]})  "),
+                @tui.text_span(content: "c", style: @hotkey_style),
+                @tui.text_span(content: ": Filled Color (#{@filled_colors[@filled_color_index][:name]})"),
+              ]),
+              # Line 3: Unfilled
+              @tui.text_line(spans: [
+                @tui.text_span(content: "u", style: @hotkey_style),
+                @tui.text_span(content: ": Unfilled Symbol (#{@unfilled_symbols[@unfilled_symbol_index][:name]})  "),
+                @tui.text_span(content: "x", style: @hotkey_style),
+                @tui.text_span(content: ": Unfilled Color (#{@unfilled_colors[@unfilled_color_index][:name]})"),
+              ]),
+            ]
+          ),
+        ]
+      )
+      frame.render_widget(controls, controls_area)
+    end
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "right"
+      @ratio_index = (@ratio_index + 1) % @ratios.length
+    in type: :key, code: "left"
+      @ratio_index = (@ratio_index - 1) % @ratios.length
+    in type: :key, code: "b"
+      @base_style_index = (@base_style_index + 1) % @base_styles.length
+    in type: :key, code: "f"
+      @filled_symbol_index = (@filled_symbol_index + 1) % @filled_symbols.length
+    in type: :key, code: "c"
+      @filled_color_index = (@filled_color_index + 1) % @filled_colors.length
+    in type: :key, code: "u"
+      @unfilled_symbol_index = (@unfilled_symbol_index + 1) % @unfilled_symbols.length
+    in type: :key, code: "x"
+      @unfilled_color_index = (@unfilled_color_index + 1) % @unfilled_colors.length
+    else
+      # Ignore other events
+      nil
+    end
+  end
+end
+
+WidgetLineGaugeDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_list_demo/README.md

@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# List Widget Example
+
+Demonstrates a selectable list with extensive configuration options.
+
+Lists are the workhorse of terminal interfaces. Managing selection state, scrolling windows, and highlight styles logic is complex. The `List` widget handles all of this.
+
+## Features Demonstrated
+
+- **Scrolling**: Automatically handles lists larger than the view area.
+- **Selection**: Maintains selected index and supports "no selection" state.
+- **Highlighting**: Custom styles and symbols (e.g., `>>`) for the selected item.
+- **Offset Modes**: Manual control over the scroll offset vs automatic "scroll to selection" behavior.
+- **Scroll Padding**: Keeping a margin of items visible above/below the selection.
+
+## Hotkeys
+
+- **i**: Cycle Item Data (`items`)
+- **Arrow Keys (↑/↓)**: Navigate (`selected_index`)
+- **x**: Toggle Selection (`selected_index`)
+- **h**: Cycle Highlight Style (`highlight_style`)
+- **y**: Cycle Highlight Symbol (`highlight_symbol`)
+- **d**: Toggle Direction (`direction`)
+- **s**: Cycle Highlight Spacing (`highlight_spacing`)
+- **p**: Cycle Scroll Padding (`scroll_padding`)
+- **b**: Cycle Base Style (`style`)
+- **r**: Toggle Repeat Highlight Symbol (`repeat_highlight_symbol`)
+- **o**: Cycle Offset Mode (`offset`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_list_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create a file explorer.
+- Build a navigation menu.
+- Display a log where users can scroll back to read history.
+- Implement "infinite select" behaviors.
+
+![Demo](/doc/images/widget_list_demo.png)

data/examples/widget_list_demo/app.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+require "faker" # Use Faker for large, realistic datasets
+
+# Demonstrates a selectable list of items with interactive attribute cycling.
+#
+# Users need to browse and select from collections of data. Lists are fundamental to terminal interfaces, but managing selection state, scrolling, and styling can be complex.
+#
+# This demo showcases the <tt>List</tt> widget. It provides an interactive playground where you can cycle through different configurations, styles, and behaviors in real-time.
+#
+# Use it to understand how to implement menus, file browsers, or any selectable collection of items.
+#
+# === Examples
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_list_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_list_demo.png
+class WidgetListDemo
+  # Initializes the demo with example data and default configuration.
+  def initialize
+    Faker::Config.random = Random.new(12345)
+    @selected_index = 6 # Start at C# to avoid highlighting the rich text examples
+    @tui_for_setup = nil
+
+    @item_sets = [
+      {
+        name: "Programming",
+        items: [
+          :ruby_styled, # Will be replaced with rich text in run()
+          :rust_styled, # Will be replaced with rich text in run()
+          :python_styled, # Will be replaced with rich text in run()
+          :javascript_styled, # Will be replaced with rich text in run()
+          "Go",
+          "C++",
+          "C#",
+          "Java",
+          "Kotlin",
+          "Swift",
+          "Objective-C",
+          "PHP",
+          "TypeScript",
+          "Perl",
+          "Lua",
+          "R",
+          "Scala",
+          "Haskell",
+          "Elixir",
+          "Clojure",
+          "Groovy",
+          "Closure",
+          "VB.NET",
+          "F#",
+          "Erlang",
+          "Lisp",
+          "Scheme",
+          "Prolog",
+          "Fortran",
+          "COBOL",
+          "Pascal",
+          "Delphi",
+          "Ada",
+          "Bash",
+          "Sh",
+          "Tcl",
+          "Awk",
+          "sed",
+          "Vim Script",
+          "PowerShell",
+          "Batch",
+          "Assembly",
+          "Wasm",
+          "WebAssembly",
+          "Julia",
+          "Matlab",
+          "Octave",
+          "BASIC",
+        ],
+      },
+      {
+        name: "Large List",
+        items: (1..200).map { |i| "Item #{i}" },
+      },
+      {
+        name: "Colors",
+        items: begin
+          Faker::Color.unique.clear
+          Array.new(100) { Faker::Color.color_name }
+        end,
+      },
+      {
+        name: "Fruits",
+        items: begin
+          Faker::Food.unique.clear
+          Array.new(100) { Faker::Food.fruits }
+        end,
+      },
+    ]
+    @item_set_index = 0
+
+    @highlight_symbol_names = [">> ", "▶ ", "→ ", "• ", "★ "]
+    @highlight_symbol_index = 0
+
+    @direction_configs = [
+      { name: "Top to Bottom", direction: :top_to_bottom },
+      { name: "Bottom to Top", direction: :bottom_to_top },
+    ]
+    @direction_index = 0
+
+    @highlight_spacing_configs = [
+      { name: "When Selected", spacing: :when_selected },
+      { name: "Always", spacing: :always },
+      { name: "Never", spacing: :never },
+    ]
+    @highlight_spacing_index = 1
+
+    @repeat_modes = [
+      { name: "Off", repeat: false },
+      { name: "On", repeat: true },
+    ]
+    @repeat_index = 0
+
+    @scroll_padding_configs = [
+      { name: "None", padding: nil },
+      { name: "1 item", padding: 1 },
+      { name: "2 items", padding: 2 },
+    ]
+    @scroll_padding_index = 1
+
+    # Offset mode configurations to demonstrate offset + selection interaction
+    @offset_modes = [
+      { name: "Auto (No Offset)", offset: nil, allow_selection: true },
+      { name: "Offset Only", offset: 10, allow_selection: false },
+      { name: "Selection + Offset (Conflict)", offset: 0, allow_selection: true },
+    ]
+    @offset_mode_index = 0
+  end
+
+  # Runs the demo application.
+  #
+  # This method enters the terminal alternate screen, starts the main loop, and handles cleanup on exit.
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+
+      # Create rich text for "Ruby" - each letter with a different red style
+      ruby_line = @tui.text_line(spans: [
+        @tui.text_span(content: "R", style: @tui.style(fg: :red, modifiers: [:underlined])),
+        @tui.text_span(content: "u", style: @tui.style(fg: :light_red, modifiers: [:bold])),
+        @tui.text_span(content: "b", style: @tui.style(fg: :red, modifiers: [:italic])),
+        @tui.text_span(content: "y", style: @tui.style(fg: :light_red, modifiers: [:reversed])),
+      ])
+
+      # Create rich text for "Rust" - single styled Span
+      rust_span = @tui.text_span(
+        content: "Rust",
+        style: @tui.style(fg: :magenta, modifiers: [:bold, :underlined])
+      )
+
+      # Create ListItem for "Python" - demonstrates content + row background
+      python_item = @tui.list_item(
+        content: @tui.text_span(content: "Python", style: @tui.style(fg: :yellow)),
+        style: @tui.style(bg: :dark_gray)
+      )
+
+      # Create ListItem for "JavaScript" - demonstrates styled text with row background
+      javascript_item = @tui.list_item(
+        content: @tui.text_line(spans: [
+          @tui.text_span(content: "Java", style: @tui.style(fg: :yellow, modifiers: [:bold])),
+          @tui.text_span(content: "Script", style: @tui.style(fg: :light_yellow, modifiers: [:italic])),
+        ]),
+        style: @tui.style(bg: :blue)
+      )
+
+      # Replace the styled placeholders
+      @item_sets[0][:items][0] = ruby_line
+      @item_sets[0][:items][1] = rust_span
+      @item_sets[0][:items][2] = python_item
+      @item_sets[0][:items][3] = javascript_item
+
+      # Initialize styles that require @tui
+      @highlight_styles = [
+        { name: "Blue on White Bold", style: @tui.style(fg: :blue, bg: :white, modifiers: [:bold]) },
+        { name: "Blue Bold", style: @tui.style(fg: :blue, modifiers: [:bold]) },
+        { name: "Yellow on Black", style: @tui.style(fg: :yellow, bg: :black) },
+        { name: "Green Italic", style: @tui.style(fg: :green, modifiers: [:italic]) },
+        { name: "White Reversed", style: @tui.style(fg: :white, modifiers: [:reversed]) },
+        { name: "Cyan Bold", style: @tui.style(fg: :cyan, modifiers: [:bold]) },
+      ]
+      @highlight_style_index = 0
+
+      @base_styles = [
+        { name: "None", style: nil },
+        { name: "Dark Gray", style: @tui.style(fg: :dark_gray) },
+        { name: "White on Black", style: @tui.style(fg: :white, bg: :black) },
+      ]
+      @base_style_index = 0
+
+      @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        render
+        break if handle_input == :quit
+
+        sleep 0.05
+      end
+    end
+  end
+
+  # :nodoc:
+  private def render
+    items = @item_sets[@item_set_index][:items]
+    direction_config = @direction_configs[@direction_index]
+    spacing_config = @highlight_spacing_configs[@highlight_spacing_index]
+    repeat_config = @repeat_modes[@repeat_index]
+    highlight_style_config = @highlight_styles[@highlight_style_index]
+    highlight_symbol = @highlight_symbol_names[@highlight_symbol_index]
+    base_style_config = @base_styles[@base_style_index]
+    scroll_padding_config = @scroll_padding_configs[@scroll_padding_index]
+    offset_mode_config = @offset_modes[@offset_mode_index]
+
+    # Determine selection/offset based on mode
+    effective_selection = offset_mode_config[:allow_selection] ? @selected_index : nil
+    effective_offset = offset_mode_config[:offset]
+    selection_label = effective_selection.nil? ? "none" : effective_selection.to_s
+    offset_label = effective_offset.nil? ? "auto" : effective_offset.to_s
+
+    @tui.draw do |frame|
+      # Split into main content and control panel
+      main_area, control_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(8),
+        ]
+      )
+
+      # Split main content into title and list
+      title_area, list_area = @tui.layout_split(
+        main_area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_length(1),
+          @tui.constraint_fill(1),
+        ]
+      )
+
+      # Render title
+      title = @tui.paragraph(text: "List Widget Demo - Interactive Attribute Cycling")
+      frame.render_widget(title, title_area)
+
+      # Render list
+      list = @tui.list(
+        items:,
+        selected_index: effective_selection,
+        offset: effective_offset,
+        style: base_style_config[:style],
+        highlight_style: highlight_style_config[:style],
+        highlight_symbol:,
+        repeat_highlight_symbol: repeat_config[:repeat],
+        highlight_spacing: spacing_config[:spacing],
+        direction: direction_config[:direction],
+        scroll_padding: scroll_padding_config[:padding],
+        block: @tui.block(
+          title: "#{@item_sets[@item_set_index][:name]} | Sel: #{selection_label} | Offset: #{offset_label}",
+          borders: [:all]
+        )
+      )
+      frame.render_widget(list, list_area)
+
+      # Render control panel
+      control_panel = @tui.block(
+        title: "Controls",
+        borders: [:all],
+        children: [
+          @tui.paragraph(
+            text: [
+              @tui.text_line(spans: [
+                @tui.text_span(content: "i", style: @hotkey_style),
+                @tui.text_span(content: ": Items  "),
+                @tui.text_span(content: "↑/↓", style: @hotkey_style),
+                @tui.text_span(content: ": Navigate  "),
+                @tui.text_span(content: "x", style: @hotkey_style),
+                @tui.text_span(content: ": Select  "),
+                @tui.text_span(content: "h", style: @hotkey_style),
+                @tui.text_span(content: ": Highlight (#{highlight_style_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "y", style: @hotkey_style),
+                @tui.text_span(content: ": Symbol (#{highlight_symbol})  "),
+                @tui.text_span(content: "d", style: @hotkey_style),
+                @tui.text_span(content: ": Direction (#{direction_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "s", style: @hotkey_style),
+                @tui.text_span(content: ": Spacing (#{spacing_config[:name]})  "),
+                @tui.text_span(content: "p", style: @hotkey_style),
+                @tui.text_span(content: ": Scroll Padding (#{scroll_padding_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "b", style: @hotkey_style),
+                @tui.text_span(content: ": Base (#{base_style_config[:name]})  "),
+                @tui.text_span(content: "r", style: @hotkey_style),
+                @tui.text_span(content: ": Repeat (#{repeat_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "o", style: @hotkey_style),
+                @tui.text_span(content: ": Offset Mode (#{offset_mode_config[:name]})  "),
+                @tui.text_span(content: "q", style: @hotkey_style),
+                @tui.text_span(content: ": Quit"),
+              ]),
+            ]
+          ),
+        ]
+      )
+      frame.render_widget(control_panel, control_area)
+    end
+  end
+
+  # :nodoc:
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "i"
+      @item_set_index = (@item_set_index + 1) % @item_sets.size
+      @selected_index = nil
+    in type: :key, code: "up"
+      items = @item_sets[@item_set_index][:items]
+      @selected_index = (@selected_index || 0) - 1
+      @selected_index = items.size - 1 if @selected_index.negative?
+    in type: :key, code: "down"
+      items = @item_sets[@item_set_index][:items]
+      @selected_index = ((@selected_index || -1) + 1) % items.size
+    in type: :key, code: "x"
+      @selected_index = @selected_index.nil? ? 0 : nil
+    in type: :key, code: "h"
+      @highlight_style_index = (@highlight_style_index + 1) % @highlight_styles.size
+    in type: :key, code: "y"
+      @highlight_symbol_index = (@highlight_symbol_index + 1) % @highlight_symbol_names.size
+    in type: :key, code: "d"
+      @direction_index = (@direction_index + 1) % @direction_configs.size
+    in type: :key, code: "s"
+      @highlight_spacing_index = (@highlight_spacing_index + 1) % @highlight_spacing_configs.size
+    in type: :key, code: "b"
+      @base_style_index = (@base_style_index + 1) % @base_styles.size
+    in type: :key, code: "r"
+      @repeat_index = (@repeat_index + 1) % @repeat_modes.size
+    in type: :key, code: "p"
+      @scroll_padding_index = (@scroll_padding_index + 1) % @scroll_padding_configs.size
+    in type: :key, code: "o"
+      @offset_mode_index = (@offset_mode_index + 1) % @offset_modes.size
+    else
+      nil
+    end
+  end
+end
+
+WidgetListDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_map_demo/README.md

@@ -0,0 +1,39 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Canvas Widget Example
+
+Demonstrates drawing custom graphics and maps using the standard Braille and Block patterns.
+
+Standard widgets are great for text, but sometimes you need to draw. The `Canvas` widget gives you a high-resolution coordinate system (x, y) to render shapes, lines, and data visualizations that go beyond the grid.
+
+## Features Demonstrated
+
+- **High-Resolution Drawing**: Using Braille patterns (`⣿`) to effectively double the vertical and horizontal resolution of the terminal.
+- **Layers**: Drawing multiple shapes (Map, Circles, Lines) in a specific order.
+- **Animation**: Updating coordinates in a loop to create smooth motion.
+- **World Map**: Using the built-in `Map` shape for geographic data.
+
+## Hotkeys
+
+- **b**: Cycle Background Color (`background_color`)
+- **m**: Cycle Marker Type (`marker`)
+- **l**: Toggle Labels (modifies `shapes`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_map_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Render geographic data (World, USA, Europe).
+- Overlay custom labels and markers on a map.
+- Animate visual elements on top of a static background.
+
+![Demo](/doc/images/widget_map_demo.png)