line-message-builder 0.7.0 → 0.9.0

data/lib/line/message/builder/flex/text.rb

@@ -4,43 +4,164 @@ module Line
   module Message
     module Builder
       module Flex
-        # The text is a component of the Flex message.
+        # Represents a "text" component in a LINE Flex Message.
+        #
+        # Text components are used to display strings of text. They offer various
+        # styling options, including font `size`, `weight` (via styles in a {Box}
+        # or {Bubble}), `color`, `align`ment, `gravity`, text `wrap`ping,
+        # `line_spacing`, and more. A text component can also have an
+        # {Actionable#action action} to make it tappable.
+        #
+        # Text components also support embedded {Span} components, which allow parts of
+        # the text to have different styling. Spans can be added to a text component
+        # using the {#span} method within the Text component block.
+        #
+        # @example Creating a text component within a box
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Text Example" do
+        #       bubble do
+        #         body do
+        #           text "Hello, Flex World!",
+        #                size: :xl,
+        #                color: "#FF0000",
+        #                wrap: true do
+        #                  message "More info", text: "Tell me more about text"
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @example Creating a text component with spans
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Span Example" do
+        #       bubble do
+        #         body do
+        #           text "This message has styled spans:" do
+        #             span "Red", color: "#FF0000"
+        #             span " and ", size: :sm
+        #             span "Bold", weight: :bold
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#text
+        # @see Actionable For making the text tappable.
+        # @see Position::Horizontal For `align` property.
+        # @see Position::Vertical For `gravity` property.
+        # @see Position::Margin For `margin` property.
+        # @see Position::Offset For offset properties.
+        # @see Size::Flex For `flex` sizing property.
+        # @see Size::Shared For common `size` keywords (e.g., `:xl`, `:sm`).
+        # @see Size::AdjustMode For `adjust_mode` property.
         class Text < Line::Message::Builder::Base
-          include Actionable
-          include Position::Horizontal
-          include Position::Vertical
-          include Position::Margin
-          include Position::Offset
-          include Size::Flex
-          include Size::Shared
-          include Size::AdjustMode
+          include Actionable           # Enables defining an action for the text.
+          include Position::Horizontal # Adds `align` option.
+          include Position::Vertical   # Adds `gravity` option.
+          include Position::Margin     # Adds `margin` option.
+          include Position::Offset     # Adds offset options.
+          include Size::Flex           # Adds `flex` option for sizing within a parent box.
+          include Size::Shared         # Adds `size` option (e.g., :sm, :md, :xl).
+          include Size::AdjustMode # Adds `adjust_mode` option.
 
-          attr_reader :text
+          # @!attribute [r] text
+          #   @return [String] The actual text content to be displayed.
+          #     This is a required attribute.
+          attr_reader :text, :contents
 
+          # Specifies whether the text should wrap or be truncated if it exceeds
+          # the component's width.
+          # @!method wrap(value)
+          #   @param value [Boolean] `true` to enable text wrapping, `false` (default) to disable.
+          #   @return [Boolean] The current wrap setting.
           option :wrap, default: false
-          option :line_spacing, default: nil
+
+          # Specifies the spacing between lines of text.
+          # Can be a pixel value (e.g., "10px") or a keyword.
+          # @!method line_spacing(value)
+          #   @param value [String, nil] The line spacing value (e.g., `"5px"`).
+          #   @return [String, nil] The current line spacing.
+          option :line_spacing, default: nil # API key: lineSpacing
+
+          # Specifies the color of the text.
+          # @!method color(value)
+          #   @param value [String, nil] Hexadecimal color code (e.g., `"#RRGGBB"`, `"#RRGGBBAA"`).
+          #   @return [String, nil] The current text color.
           option :color, default: nil
 
-          def initialize(text, context: nil, **options, &)
-            @text = text
+          # Initializes a new Flex Message Text component.
+          #
+          # @param text_content [String] The text to display. This is required.
+          # @param context [Object, nil] An optional context for the builder.
+          # @param options [Hash] A hash of options to set instance variables
+          #   (e.g., `:wrap`, `:color`, `:size`, and options from included modules).
+          # @param block [Proc, nil] An optional block, typically used to define an
+          #   {Actionable#action action} for the text.
+          # @raise [ArgumentError] if `text_content` is nil (though the more specific
+          #   `RequiredError` is raised in `to_h`).
+          def initialize(text_content = nil, context: nil, **options, &)
+            @text = text_content # The text content is mandatory.
+            @contents = []       # Initialize contents for spans, if any.
 
-            super(context: context, **options, &)
+            super(context: context, **options, &) # Sets options and evals block (for action).
           end
 
+          # A convenience DSL method to set the `wrap` property to `true`.
+          #
+          # @example
+          #   text_component.text "Long text..."
+          #   text_component.wrap! # Enables text wrapping
+          #
+          # @return [true]
           def wrap!
-            @wrap = true
+            wrap(true) # Use the setter generated by `option`
+          end
+
+          # Adds a {Span} component to this text component's contents.
+          #
+          # Spans allow different styling for parts of the text, such as color,
+          # weight, size, and decoration.
+          #
+          # @param text_content [String] The span text content.
+          # @param options [Hash] Options for the span. See {Span#initialize}.
+          # @param block [Proc, nil] An optional block for advanced span configuration.
+          # @return [Flex::Span] The newly created Span object.
+          # @example
+          #   text "Message with spans:" do
+          #     span "Important", color: "#FF0000", weight: :bold
+          #     span " normal text"
+          #   end
+          def span(text_content, **options, &)
+            @contents << Span.new(text_content, context: @context, **options, &)
+          end
+
+          def any_content?
+            !contents.empty? || !text.nil?
           end
 
-          def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-            raise RequiredError, "text is required" if text.nil?
+          def to_h
+            raise RequiredError, "text content is required for a text component" unless any_content?
 
+            return to_sdkv2 if context.sdkv2?
+
+            to_api
+          end
+
+          private
+
+          def to_api # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             {
               type: "text",
               text: text,
-              wrap: wrap,
-              # Position
-              align: align,
-              gravity: gravity,
+              contents: contents.map(&:to_h), # Convert spans to hash
+              wrap: wrap,               # From option
+              color: color,             # From option
+              lineSpacing: line_spacing, # From option (maps to API key)
+              # Position::Horizontal & Position::Vertical
+              align: align,     # From Position::Horizontal
+              gravity: gravity, # From Position::Vertical
               # Position::Margin
               margin: margin,
               # Position::Offset
@@ -51,13 +172,40 @@ module Line
               offsetEnd: offset_end,
               # Size::Flex
               flex: flex,
-              # Size::Shared
-              size: size,
-              # Size::AdjustMode
-              adjustMode: adjust_mode,
-              lineSpacing: line_spacing,
-              color: color,
-              action: action&.to_h
+              # Size::Shared & Size::AdjustMode
+              size: size,               # From Size::Shared
+              adjustMode: adjust_mode,  # From Size::AdjustMode
+              # Actionable
+              action: action&.to_h # From Actionable module
+            }.compact
+          end
+
+          def to_sdkv2 # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            {
+              type: "text",
+              text: text,
+              contents: contents.map(&:to_h), # Convert spans to hash
+              wrap: wrap,               # From option
+              color: color,             # From option
+              line_spacing: line_spacing, # From option (maps to API key)
+              # Position::Horizontal & Position::Vertical
+              align: align,     # From Position::Horizontal
+              gravity: gravity, # From Position::Vertical
+              # Position::Margin
+              margin: margin,
+              # Position::Offset
+              position: position,
+              offset_top: offset_top,
+              offset_bottom: offset_bottom,
+              offset_start: offset_start,
+              offset_end: offset_end,
+              # Size::Flex
+              flex: flex,
+              # Size::Shared & Size::AdjustMode
+              size: size, # From Size::Shared
+              adjust_mode: adjust_mode, # From Size::AdjustMode
+              # Actionable
+              action: action&.to_h # From Actionable module
             }.compact
           end
         end

data/lib/line/message/builder/flex.rb

@@ -3,25 +3,69 @@
 module Line
   module Message
     module Builder
-      # The Flex module allows to build Flex messages.
+      # The `Line::Message::Builder::Flex` module serves as the primary namespace
+      # for all classes, modules, and components related to the construction of
+      # LINE Flex Messages within the `line-message-builder` gem.
+      #
+      # Flex Messages are highly customizable messages that can display rich content
+      # with various layouts, components, and interactive elements. This module
+      # organizes the DSL for building these messages.
+      #
+      # This file (`lib/line/message/builder/flex.rb`) is responsible for loading
+      # all necessary sub-components and builder logic for Flex Messages, such as:
+      # - {Flex::Builder}: The main class used to construct a complete Flex Message object.
+      # - Container components: {Flex::Bubble}, {Flex::Carousel}.
+      # - Basic components: {Flex::Box}, {Flex::Text}, {Flex::Button}, {Flex::Image}.
+      # - Mixin modules for shared functionality: {Flex::Actionable},
+      #   modules within {Flex::Position} and {Flex::Size}.
+      # - The partial system: {Flex::HasPartial} and {Flex::Partial}.
+      #
+      # While this module itself is a namespace, the actual process of building a
+      # Flex Message typically starts within a {Line::Message::Builder::Container}
+      # block, by calling the `flex` method on the container. This method then
+      # instantiates and uses {Flex::Builder} to define the Flex Message structure.
+      #
+      # @example How a Flex Message is typically initiated (conceptual)
+      #   Line::Message::Builder.with do
+      #     # This `flex` call on root_container would utilize Flex::Builder
+      #     flex alt_text: "My Flex Message"  do
+      #       bubble do
+      #         # ... define bubble content ...
+      #       end
+      #     end
+      #   end
+      #
+      # @see Flex::Builder For the main Flex Message construction entry point.
+      # @see Flex::Bubble
+      # @see Flex::Carousel
+      # @see Flex::Box
+      # @see Flex::Text
+      # @see Flex::Button
+      # @see Flex::Image
+      # @see https://developers.line.biz/en/docs/messaging-api/using-flex-messages/
       module Flex
+        # Main builder for the entire Flex Message object
         require_relative "flex/builder"
+
+        # Mixin modules for component capabilities
         require_relative "flex/actionable"
-        require_relative "flex/position"
-        require_relative "flex/size"
+        require_relative "flex/position" # For positioning options (margin, padding, etc.)
+        require_relative "flex/size"     # For sizing options (flex factor, specific sizes)
 
-        # Partial
+        # Partial system for reusable components
         require_relative "flex/partial"
 
-        # Container
-        require_relative "flex/bubble"
-        require_relative "flex/carousel"
+        # Container-type components
+        require_relative "flex/bubble"   # Individual message unit
+        require_relative "flex/carousel" # Horizontally scrollable list of bubbles
 
-        # Components
-        require_relative "flex/box"
-        require_relative "flex/text"
-        require_relative "flex/button"
-        require_relative "flex/image"
+        # Basic building-block components
+        require_relative "flex/box"      # Layout container
+        require_relative "flex/text"     # Text display
+        require_relative "flex/button"   # Interactive button
+        require_relative "flex/image"    # Image display
+        require_relative "flex/separator" # Visual separator
+        require_relative "flex/span" # Text span for styling parts of text
       end
     end
   end

data/lib/line/message/builder/quick_reply.rb

@@ -13,19 +13,21 @@ module Line
 
         def message(text, label:, image_url: nil, &)
           action(
-            Actions::Message.new(text, label: label, &),
+            Actions::Message.new(text, context: context, label: label, &),
             image_url
           )
         end
 
         def postback(data, label: nil, display_text: nil, image_url: nil, &)
           action(
-            Actions::Postback.new(data, label: label, display_text: display_text, &),
+            Actions::Postback.new(data, context: context, label: label, display_text: display_text, &),
             image_url
           )
         end
 
-        def to_h
+        private
+
+        def to_api
           {
             items: @items.map do |item, image_url|
               {
@@ -37,7 +39,17 @@ module Line
           }
         end
 
-        private
+        def to_sdkv2
+          {
+            items: @items.map do |item, image_url|
+              {
+                type: "action",
+                image_url: image_url,
+                action: item.to_h
+              }
+            end
+          }
+        end
 
         def action(action, image_url)
           @items << [action, image_url]

data/lib/line/message/builder/text.rb

@@ -13,7 +13,9 @@ module Line
           super(context: context, **options, &block)
         end
 
-        def to_h
+        private
+
+        def to_api
           {
             type: "text",
             text: @text,
@@ -21,6 +23,15 @@ module Line
             quickReply: @quick_reply&.to_h
           }.compact
         end
+
+        def to_sdkv2
+          {
+            type: "text",
+            text: @text,
+            quote_token: quote_token,
+            quick_reply: @quick_reply&.to_h
+          }.compact
+        end
       end
     end
   end

data/lib/line/message/builder/version.rb

@@ -3,7 +3,7 @@
 module Line
   module Message
     module Builder
-      VERSION = "0.7.0"
+      VERSION = "0.9.0"
     end
   end
 end

data/lib/line/message/builder.rb

@@ -4,10 +4,23 @@ require_relative "builder/version"
 
 module Line
   module Message
-    # The Builder module provides a DSL for building LINE messages.
+    # The Builder module provides a Domain Specific Language (DSL) for constructing
+    # and validating LINE messages. It offers a structured and intuitive way to
+    # define various message types, such as text, flex messages, and quick replies,
+    # ensuring they adhere to the LINE Messaging API specifications.
+    #
+    # This module simplifies the process of creating complex message structures
+    # by providing a set of builder classes and helper methods.
     module Builder
+      # Base error class for all errors raised by the Line::Message::Builder module.
+      # This allows for rescuing any specific builder error or all builder errors.
       class Error < StandardError; end
+      # Error raised when a required attribute or element is missing during message construction.
+      # For example, if a text message is created without specifying the text content.
       class RequiredError < Error; end
+      # Error raised when an attribute or element fails validation rules.
+      # For example, if a URL provided for an action is invalid or if a text
+      # message exceeds the maximum allowed length.
       class ValidationError < Error; end
 
       require_relative "builder/context"
@@ -21,8 +34,25 @@ module Line
 
       module_function
 
-      def with(context = nil, &)
-        Container.new(context: context, &)
+      # Entry point for building a message container.
+      # This method initializes a new message {Container} and evaluates the
+      # provided block within the context of that container.
+      #
+      # @param context [Object, nil] An optional context object that can be made
+      #   available within the builder block. This can be useful for accessing
+      #   helper methods or data within the block.
+      # @param mode [Symbol] The mode to use for building messages. Can be either
+      #   `:api` (default) for direct LINE Messaging API format or `:sdkv2` for
+      #   LINE Bot SDK v2 compatible format.
+      # @yield [container] The block is yielded with the newly created {Container}
+      #   instance, allowing you to define the message structure using the DSL.
+      # @return [Container] The initialized message container with the defined structure.
+      # @example
+      #   message = Line::Message::Builder.with do
+      #     text "Hello, world!"
+      #   end
+      def with(context = nil, mode: :api, &)
+        Container.new(context: context, mode: mode, &)
       end
     end
   end

data/lib/line/message/rspec/matchers/have_flex_component.rb

@@ -49,6 +49,7 @@ module Line
               end || @expected.call(content)
             end
 
+            # Directly check if this is the component we're looking for
             @expected.call(content)
           end
 
@@ -114,6 +115,16 @@ module Line
             ::RSpec::Matchers::BuiltIn::Include.new({ "url" => url, **options }).matches?(content)
           end
         end
+
+        def have_line_flex_span(text, **options) # rubocop:disable Naming/PredicateName
+          options = Utils.stringify_keys!(options, deep: true)
+
+          HaveFlexComponent.new(expected_desc: "span(#{text.inspect})") do |content|
+            next false unless content["type"] == "span"
+
+            content["text"].match?(text) && ::RSpec::Matchers::BuiltIn::Include.new(options).matches?(content)
+          end
+        end
       end
     end
   end

data/lib/line/message/rspec/matchers/have_flex_separator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Line
+  module Message
+    module RSpec
+      # :nodoc:
+      module Matchers
+        def have_line_flex_separator(**options) # rubocop:disable Naming/PredicateName
+          options = Utils.stringify_keys!(options, deep: true)
+
+          HaveFlexComponent.new(expected_desc: "separator(#{options.inspect})") do |content|
+            next false unless content["type"] == "separator"
+
+            options.empty? || ::RSpec::Matchers::BuiltIn::Include.new(options).matches?(content)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/line/message/rspec/matchers.rb

@@ -6,3 +6,4 @@ require_relative "matchers/have_quick_reply"
 require_relative "matchers/have_flex_message"
 require_relative "matchers/have_flex_bubble"
 require_relative "matchers/have_flex_component"
+require_relative "matchers/have_flex_separator"

data/lib/line/message/rspec.rb

@@ -1,3 +1,17 @@
 # frozen_string_literal: true
 
+# This file serves as the main entry point for RSpec matchers related to the
+# `line-message` gem. When `require "line/message/rspec"` is used in a
+# RSpec test suite, this file is loaded, and it, in turn, loads the
+# necessary files to make the custom matchers available for testing
+# `Line::Message::Builder` objects and their outputs.
+#
+# By requiring this file, developers gain access to specialized matchers
+# designed to simplify the testing of message structures built with
+# `line-message`.
+#
+# @example in `spec_helper.rb` or a specific test file
+#   require "line/message/rspec"
+#
+# @see Line::Message::Rspec::Matchers
 require "line/message/rspec/matchers"