charming 0.1.0

data/lib/charming/ui.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Charming
+  # UI is a module of layout primitives for composing and positioning ANSI-styled
+  # terminal text. It provides functions to join blocks horizontally or vertically,
+  # place content on fixed-size canvases, overlay elements, and slice strings that
+  # contain ANSI escape sequences while preserving their styling.
+  module UI
+    module_function
+
+    # Builds a new {Style} instance for chaining color, padding, alignment, and other visual properties.
+    def style
+      Style.new
+    end
+
+    # Horizontally concatenates *blocks* into a single multi-line string, padding each block's
+    # rows to match the widest row. A *gap* argument (in spaces) can separate adjacent columns.
+    def join_horizontal(*blocks, gap: 0)
+      normalized = normalize_blocks(blocks)
+      widths = block_widths(normalized)
+      separator = " " * gap
+
+      Array.new(block_height(normalized)) do |index|
+        horizontal_line(normalized, widths, index).join(separator)
+      end.join("\n")
+    end
+
+    # Stacks *blocks* vertically separated by one or more blank lines. A *gap* of N inserts N
+    # extra newline characters between blocks (1 gap = 1 blank line, 2 gaps = 2 blank lines, etc.).
+    def join_vertical(*blocks, gap: 0)
+      blocks.join("\n" * (gap + 1))
+    end
+
+    # Centers a *block* within a canvas of the given *width* and *height*, then returns the result.
+    def center(block, width:, height:, background: nil)
+      place(block, width: width, height: height, top: :center, left: :center, background: background)
+    end
+
+    # Draws *overlay* on top of a base at the specified *top* (row) and *left* (column) coordinates,
+    # defaulting to center in both directions. ANSI styling on the base content is preserved underneath.
+    def overlay(base, overlay, top: :center, left: :center)
+      base_lines = base.to_s.lines(chomp: true)
+      overlay_lines = overlay.to_s.lines(chomp: true)
+      width = block_width(base_lines)
+      row = offset(top, base_lines.length, overlay_lines.length)
+      column = offset(left, width, block_width(overlay_lines))
+
+      draw_lines(base_lines, overlay_lines, row: row, column: column, width: width)
+    end
+
+    # Places a *block* onto a blank canvas of *width* × *height* at an offset determined by *top* (row)
+    # and *left* (column). Non-:center values are treated as absolute positions. When *background* is
+    # given, the assembled frame is wrapped so the theme bg paints the entire canvas — overlay content
+    # with its own bg overrides per-cell; resets re-apply the canvas bg.
+    def place(block, width:, height:, top: 0, left: 0, background: nil)
+      lines = block.to_s.lines(chomp: true)
+      row = offset(top, height, lines.length)
+      column = offset(left, width, block_width(lines))
+      canvas = Array.new(height) { " " * width }
+      composed = draw_lines(canvas, lines, row: row, column: column, width: width)
+      return composed unless background
+
+      Style.new.background(background).render(composed)
+    end
+
+    # Normalizes an array of mixed objects into arrays of lines by calling `#to_s` on each element.
+    def normalize_blocks(blocks)
+      blocks.map { |block| block.to_s.lines(chomp: true) }
+    end
+
+    # Measures the displayed (visual) width of each normalised block, returning an array of integer widths.
+    def block_widths(blocks)
+      blocks.map { |lines| lines.map { |line| Width.measure(line) }.max || 0 }
+    end
+
+    # Returns the maximum visual character width across all *lines*, accounting for multi-column characters
+    # (e.g., full-width CJK glyphs) and invisible ANSI escape sequences.
+    def block_width(lines)
+      lines.map { |line| Width.measure(line) }.max || 0
+    end
+
+    # Returns the height in rows of each normalised block, taking the maximum across all blocks.
+    def block_height(blocks)
+      blocks.map(&:length).max || 0
+    end
+
+    # Builds a single horizontal row by concatenating one line from each *block* at index *index*, padding
+    # every segment to its corresponding *width* in spaces. Returns the assembled array of padded segments.
+    def horizontal_line(blocks, widths, index)
+      blocks.each_with_index.map do |lines, block_index|
+        line = lines[index] || ""
+        line + (" " * (widths[block_index] - Width.measure(line)))
+      end
+    end
+
+    # Computes a placement coordinate: if *value* is `:center` the result centres the *size* within *available*;
+    # otherwise *value* is returned verbatim as an absolute integer position.
+    def offset(value, available, size)
+      return [(available - size) / 2, 0].max if value == :center
+
+      value
+    end
+
+    # Merges an *overlay_line* into a *base_line* at the given *column*, returning the combined string. The
+    # overlay replaces (covers) underlying characters; anything to the right that exceeds *width* is truncated.
+    def composed_overlay_line(base_line, overlay_line, column, width)
+      return visible_slice(base_line, 0, width) if column >= width
+      return visible_slice(base_line, 0, width) if column + Width.measure(overlay_line) <= 0
+
+      target_column = [column, 0].max
+      overlay_start = [0 - column, 0].max
+      overlay = visible_slice(overlay_line, overlay_start, width - target_column)
+      overlay_width = Width.measure(overlay)
+      return visible_slice(base_line, 0, width) if overlay_width.zero?
+
+      right_column = target_column + overlay_width
+
+      visible_slice(base_line, 0, target_column) +
+        overlay +
+        visible_slice(base_line, right_column, [width - right_column, 0].max)
+    end
+
+    # Returns a visible-slice of *line* starting at *start_column* spanning *width* characters, preserving any
+    # ANSI escape sequences that were active at the start of the slice. Non-positive widths return `""`.
+    def visible_slice(line, start_column, width)
+      return "" unless width.positive?
+
+      slice_visible_text(line.to_s, start_column, start_column + width)
+    end
+
+    # Slices a string by visible terminal columns while preserving ANSI style state.
+    def slice_visible_text(line, start_column, end_column)
+      state = {column: 0, output: +"", active: [], started: false, styled: false}
+
+      each_ansi_or_char(line) do |token, ansi|
+        if ansi
+          slice_ansi(token, state, start_column, end_column)
+        else
+          slice_char(token, state, start_column, end_column)
+        end
+      end
+
+      terminate_slice(state)
+    end
+
+    # Splits a *line* into token-range pieces bounded by *start_column* and *end_column*, preserving ANSI escapes
+    # that fall within the visible range. Yields each character or escape sequence along with whether it is ANSI.
+    def each_ansi_or_char(line)
+      index = 0
+      while index < line.length
+        match = line.match(Width::ANSI_PATTERN, index)
+        if match&.begin(0) == index
+          yield match[0], true
+          index = match.end(0)
+        else
+          char = line[index]
+          yield char, false
+          index += 1
+        end
+      end
+    end
+
+    # Slices an ANSI *token* (escape sequence) into *state*, writing active markers to the output if the current
+    # *column* falls within the [start_column, end_column) range. Resets styles on `[0m` sequences.
+    def slice_ansi(token, state, start_column, end_column)
+      started = state[:started]
+      update_active_styles(state[:active], token)
+      return unless state[:column].between?(start_column, end_column - 1)
+
+      start_slice(state)
+      if started
+        state[:output] << token
+        state[:styled] = !token.include?("[0m")
+      end
+    end
+
+    # Slices a plain *char* into *state*, advancing the column tracker by the character's visual width. If the
+    # character overlaps with the [start_column, end_column) range it is appended to the output.
+    def slice_char(char, state, start_column, end_column)
+      char_width = Width.measure(char)
+      char_start = state[:column]
+      char_end = char_start + char_width
+      state[:column] = char_end
+      return unless char_end > start_column && char_start < end_column
+
+      start_slice(state)
+      state[:output] << char
+    end
+
+    # Starts writing to the output buffer, flushing any active ANSI markers if this is the first character placed.
+    def start_slice(state)
+      return if state[:started]
+
+      state[:output] << state[:active].join
+      state[:styled] = true unless state[:active].empty?
+      state[:started] = true
+    end
+
+    # Closes the slice by appending a final `[0m` reset escape to the output unless no active styling exists or
+    # nothing was written. Returns the fully constructed output string with trailing reset applied.
+    def terminate_slice(state)
+      return state[:output] if !state[:styled] || state[:output].empty?
+
+      "#{state[:output]}\e[0m"
+    end
+
+    # Updates *state*[:active] with an ANSI *token*: resets all active styles on `[0m` or appends the token as a
+    # new active marker otherwise. Called during each_ansi_or_char iteration.
+    def update_active_styles(active, token)
+      if token.include?("[0m")
+        active.clear
+      else
+        active << token
+      end
+    end
+
+    # Overlays *lines* onto a *canvas* starting at (*row*, *column*), writing each overlaid line into the canvas
+    # via `composed_overlay_line`. Returns the final canvas joined by newlines.
+    def draw_lines(canvas, lines, row:, column:, width:)
+      lines.each_with_index do |line, index|
+        line_index = row + index
+        next if line_index.negative? || line_index >= canvas.length
+
+        canvas[line_index] = composed_overlay_line(canvas[line_index], line, column, width)
+      end
+
+      canvas.join("\n")
+    end
+  end
+end

data/lib/charming/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Charming
+  VERSION = "0.1.0"
+end

data/lib/charming/view.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Charming
+  # View is the base class for all screen view implementations. It provides assign injection (via `initialize`),
+  # rendering hooks, layout composition helpers (`row`, `column`, `render_component`, `yield_content`),
+  # and access to controller theme, style, and focus state from within views.
+  class View
+    # Initializes the view with named assigns injected as instance-local accessor methods via
+    # `define_singleton_method`. Called when a controller instantiates a view for rendering.
+    def initialize(**assigns)
+      @assigns = assigns
+      define_assign_readers
+    end
+
+    # Returns all view assigns as a hash, used by layouts to compose the full template (content + screen + controller).
+    def layout_assigns
+      assigns
+    end
+
+    # Renders the view's body. Default is empty — subclasses override to return visible text.
+    def render
+      ""
+    end
+
+    # Delegates focus checking to the controller in assigns, allowing views to determine which slot (sidebar, content) has focus.
+    def focused?(slot)
+      ctrl = assigns[:focus_controller] || assigns[:controller]
+      ctrl ? ctrl.focused?(slot) : false
+    end
+
+    private
+
+    attr_reader :assigns
+
+    # Returns the shared UI style configuration used by components and views for visual rendering (colors, borders).
+    def style
+      UI.style
+    end
+
+    # Returns the active theme: uses `theme` from assigns or controller, falling back to `UI::Theme.default`.
+    def theme
+      assigns[:theme] || assigns[:controller]&.theme || UI::Theme.default
+    end
+
+    # Outputs styled text through the view's rendering pipeline. Accepts a named `style:` for inline formatting.
+    # Appends the rendered value to the output buffer and returns it.
+    def text(value, style: nil)
+      rendered = apply_style(value.to_s, style)
+      append_to_buffer(rendered)
+      rendered
+    end
+
+    # Renders a box with optional styling. Accepts an inline block for complex content or a plain value.
+    # Used for bordered containers and field groups in views.
+    def box(value = nil, style: nil, &)
+      content = block_given? ? capture(&) : value.to_s
+      apply_style(content, style)
+    end
+
+    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports a `gap:` parameter.
+    def row(*items, gap: 0)
+      UI.join_horizontal(*items, gap: gap)
+    end
+
+    # Stacks items vertically using the UI rendering engine. Supports a `gap:` parameter for spacing.
+    def column(*items, gap: 0)
+      UI.join_vertical(*items, gap: gap)
+    end
+
+    # Renders a component (e.g., a ProgressBar, Spinner, Modal) and returns its string output.
+    def render_component(component)
+      component.render.to_s
+    end
+
+    # Renders a partial view component. An alias for `render_component` used in layout templates.
+    def render_partial(partial)
+      render_component(partial)
+    end
+
+    # Yields the layout's `content` slot — used by view templates to inject their body into a layout wrapper (e.g., sidebar).
+    def yield_content
+      assigns.fetch(:content, "")
+    end
+
+    # Evaluates a block in the view's context with a clean output buffer. Captures text written via `text`/`box`
+    # and returns joined content. Resets buffer afterward for parent rendering.
+    def capture(&)
+      previous_buffer = @output_buffer
+      @output_buffer = []
+      result = instance_eval(&)
+      @output_buffer.empty? ? result.to_s : @output_buffer.join("\n")
+    ensure
+      @output_buffer = previous_buffer
+    end
+
+    # Appends a value to the current output buffer (if one is active). Used by rendering helpers.
+    def append_to_buffer(value)
+      @output_buffer << value if @output_buffer
+    end
+
+    # Applies a style object's `render` method to a string, returning styled output or raw text when style is nil.
+    def apply_style(value, style_object)
+      style_object ? style_object.render(value) : value
+    end
+
+    # Dynamically defines read-only accessor methods for each assign key as singleton methods on self.
+    # Skips keys where the view already responds (controller methods take precedence).
+    def define_assign_readers
+      assigns.each_key do |name|
+        next if respond_to?(name, true)
+
+        define_singleton_method(name) { assigns.fetch(name) }
+      end
+    end
+  end
+end

data/lib/charming.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "cli" => "CLI",
+  "ui" => "UI",
+  "tty_backend" => "TTYBackend"
+)
+loader.setup
+
+module Charming
+  class Error < StandardError; end
+
+  def self.run(application, backend: nil)
+    Runtime.new(application, backend: backend).run
+  end
+
+  def self.key_of(event)
+    key = event.respond_to?(:key) ? event.key : event
+    key.to_sym
+  end
+end

data/sig/charming.rbs

@@ -0,0 +1,3 @@
+module Charming
+  VERSION: String
+end

metadata

@@ -0,0 +1,225 @@
+--- !ruby/object:Gem::Specification
+name: charming
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- pando
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.2
+- !ruby/object:Gem::Dependency
+  name: tty-cursor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: tty-progressbar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: tty-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: tty-reader
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: tty-screen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: unicode-display_width
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: Charming brings Rails-like application, routing, controller, and rendering
+  conventions to Ruby terminal user interfaces.
+email:
+- pandorocks@proton.me
+executables:
+- charming
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/charming
+- lib/charming.rb
+- lib/charming/application.rb
+- lib/charming/application_model.rb
+- lib/charming/cli.rb
+- lib/charming/component.rb
+- lib/charming/components/activity_indicator.rb
+- lib/charming/components/command_palette.rb
+- lib/charming/components/keyboard_handler.rb
+- lib/charming/components/list.rb
+- lib/charming/components/modal.rb
+- lib/charming/components/progressbar.rb
+- lib/charming/components/spinner.rb
+- lib/charming/components/table.rb
+- lib/charming/components/text_input.rb
+- lib/charming/components/viewport.rb
+- lib/charming/controller.rb
+- lib/charming/focus.rb
+- lib/charming/generators.rb
+- lib/charming/generators/app_file_generator.rb
+- lib/charming/generators/app_generator.rb
+- lib/charming/generators/app_generator/app_spec_templates.rb
+- lib/charming/generators/app_generator/basic_templates.rb
+- lib/charming/generators/app_generator/component_templates.rb
+- lib/charming/generators/app_generator/controller_template.rb
+- lib/charming/generators/app_generator/layout_template.rb
+- lib/charming/generators/app_generator/model_templates.rb
+- lib/charming/generators/app_generator/screen_spec_templates.rb
+- lib/charming/generators/app_generator/view_template.rb
+- lib/charming/generators/base.rb
+- lib/charming/generators/component_generator.rb
+- lib/charming/generators/controller_generator.rb
+- lib/charming/generators/name.rb
+- lib/charming/generators/screen_generator.rb
+- lib/charming/generators/view_generator.rb
+- lib/charming/internal/renderer/differential.rb
+- lib/charming/internal/renderer/full_repaint.rb
+- lib/charming/internal/terminal/adapter.rb
+- lib/charming/internal/terminal/memory_backend.rb
+- lib/charming/internal/terminal/tty_backend.rb
+- lib/charming/key_event.rb
+- lib/charming/mouse_event.rb
+- lib/charming/resize_event.rb
+- lib/charming/response.rb
+- lib/charming/router.rb
+- lib/charming/runtime.rb
+- lib/charming/screen.rb
+- lib/charming/task.rb
+- lib/charming/task_event.rb
+- lib/charming/task_executor.rb
+- lib/charming/timer_event.rb
+- lib/charming/ui.rb
+- lib/charming/ui/border.rb
+- lib/charming/ui/style.rb
+- lib/charming/ui/theme.rb
+- lib/charming/ui/themes/phosphor.json
+- lib/charming/ui/width.rb
+- lib/charming/version.rb
+- lib/charming/view.rb
+- sig/charming.rbs
+homepage: https://github.com/pandorocks/charming
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pandorocks/charming
+  source_code_uri: https://github.com/pandorocks/charming
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.12
+specification_version: 4
+summary: A Rails-inspired TUI framework for Ruby.
+test_files: []