charming 0.1.0 → 0.1.1

data/lib/charming/ui/theme.rb

@@ -1,178 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Charming
-  module UI
-    class Theme
-      BUILT_IN_ROOT = File.expand_path("themes", __dir__)
-
-      DEFAULT_TOKENS = {
-        text: {foreground: :bright_white},
-        title: {foreground: :bright_cyan, bold: true},
-        muted: {foreground: :bright_black},
-        border: {foreground: :bright_magenta},
-        selected: {reverse: true},
-        info: {foreground: :bright_cyan},
-        warn: {foreground: :yellow}
-      }.freeze
-
-      def self.default
-        @default ||= load_builtin("phosphor")
-      end
-
-      def self.load_file(path)
-        from_hash(JSON.parse(File.read(path)))
-      end
-
-      def self.load_builtin(name)
-        load_file(built_in_path(name))
-      end
-
-      def self.built_in_names
-        Dir.glob(File.join(BUILT_IN_ROOT, "*.json")).map { |path| File.basename(path, ".json") }.sort
-      end
-
-      def self.from_hash(value)
-        raise ArgumentError, "theme file must contain an object" unless value.is_a?(Hash)
-
-        styles = value.fetch("styles") do
-          raise ArgumentError, "theme file must contain styles"
-        end
-
-        palette = value.fetch("palette", {})
-        new(
-          resolve_palette_references(styles, palette),
-          background: resolve_background(value["background"], palette)
-        )
-      end
-
-      def self.resolve_background(value, palette)
-        return unless value
-
-        deep_resolve_colors(value, normalize_colors(palette))
-      end
-
-      def self.built_in_path(name)
-        slug = name.to_s
-        raise ArgumentError, "unknown built-in theme: #{name.inspect}" unless built_in_names.include?(slug)
-
-        File.join(BUILT_IN_ROOT, "#{slug}.json")
-      end
-
-      def self.resolve_palette_references(styles, palette)
-        palette = normalize_colors(palette)
-        deep_resolve_colors(styles, palette)
-      end
-
-      def self.deep_resolve_colors(value, palette)
-        case value
-        when Hash
-          value.transform_values { |item| deep_resolve_colors(item, palette) }
-        when Array
-          value.map { |item| deep_resolve_colors(item, palette) }
-        when String
-          palette.fetch(value, normalize_color(value) || value)
-        else
-          value
-        end
-      end
-
-      def self.normalize_colors(values)
-        values.transform_values { |value| normalize_color(value) }.compact
-      end
-
-      def self.normalize_color(value)
-        return unless value.is_a?(String)
-
-        case value
-        when /\A#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])(?:[0-9a-fA-F])?\z/
-          "#{$1 * 2}#{$2 * 2}#{$3 * 2}".prepend("#")
-        when /\A#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?\z/
-          value[0, 7]
-        end
-      end
-
-      attr_reader :background
-
-      def initialize(tokens = {}, background: nil)
-        @tokens = symbolize_keys(tokens)
-        @background = background
-      end
-
-      def style(name)
-        spec = @tokens.fetch(name.to_sym) do
-          raise ArgumentError, "unknown theme token: #{name.inspect}"
-        end
-
-        build_style(spec)
-      end
-      alias_method :[], :style
-
-      def method_missing(name, ...)
-        return style(name) if @tokens.key?(name)
-
-        super
-      end
-
-      def respond_to_missing?(name, include_private = false)
-        @tokens.key?(name) || super
-      end
-
-      private
-
-      def build_style(spec)
-        return spec if spec.is_a?(Style)
-        return UI.style.foreground(spec) unless spec.is_a?(Hash)
-
-        apply_options(UI.style, symbolize_keys(spec))
-      end
-
-      def apply_options(base_style, spec)
-        styled = apply_colors(base_style, spec)
-        styled = apply_attributes(styled, spec)
-        apply_layout(styled, spec)
-      end
-
-      def apply_colors(base_style, spec)
-        styled = base_style
-        styled = styled.foreground(spec[:foreground] || spec[:fg]) if spec.key?(:foreground) || spec.key?(:fg)
-        styled = styled.background(spec[:background] || spec[:bg]) if spec.key?(:background) || spec.key?(:bg)
-        styled
-      end
-
-      def apply_attributes(base_style, spec)
-        Style::ATTRIBUTES.each_key.reduce(base_style) do |styled, attribute|
-          spec[attribute] ? styled.public_send(attribute) : styled
-        end
-      end
-
-      def apply_layout(base_style, spec)
-        styled = base_style
-        styled = styled.padding(*Array(spec[:padding])) if spec.key?(:padding)
-        styled = apply_border(styled, spec[:border]) if spec.key?(:border)
-        styled = styled.width(spec[:width]) if spec.key?(:width)
-        styled = styled.height(spec[:height]) if spec.key?(:height)
-        styled = styled.align(spec[:align].to_sym) if spec.key?(:align)
-        styled
-      end
-
-      def apply_border(base_style, border_spec)
-        return base_style.border(border_spec) unless border_spec.is_a?(Hash)
-
-        border_spec = symbolize_keys(border_spec)
-        base_style.border(
-          border_spec.fetch(:style, :normal),
-          sides: border_spec[:sides],
-          foreground: border_spec[:foreground] || border_spec[:fg]
-        )
-      end
-
-      def symbolize_keys(value)
-        value.each_with_object({}) do |(key, item), result|
-          result[key.to_sym] = item.is_a?(Hash) ? symbolize_keys(item) : item
-        end
-      end
-    end
-  end
-end

data/lib/charming/ui/width.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-require "unicode/display_width"
-
-module Charming
-  module UI
-    # Width is a namespace for measuring and normalising the visual width of strings that may contain
-    # ANSI escape sequences. It delegates to `Unicode::DisplayWidth` while automatically stripping
-    # formatting codes so layout primitives can calculate exact character positions.
-    module Width
-      ANSI_PATTERN = /\e\[[0-9;]*m/
-
-      module_function
-
-      def measure(value)
-        Unicode::DisplayWidth.of(strip_ansi(value.to_s))
-      end
-
-      def strip_ansi(value)
-        value.to_s.gsub(ANSI_PATTERN, "")
-      end
-    end
-  end
-end

data/lib/charming/ui.rb

@@ -1,230 +0,0 @@
-# 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/view.rb

@@ -1,116 +0,0 @@
-# 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