line-message-builder 0.7.0 → 0.9.0

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

@@ -3,31 +3,151 @@
 module Line
   module Message
     module Builder
-      # The container class is main container to manage messages.
-      class Container < Base
+      # The `Container` class is the top-level entry point for constructing a batch
+      # of LINE messages using the builder DSL. It acts as a holder for one or
+      # more individual message objects (such as {Text} or {Flex} messages).
+      #
+      # When you use `Line::Message::Builder.with {}`, you are operating within
+      # the context of a `Container` instance. This container allows you to define
+      # multiple messages that can be sent together in a single API call to LINE,
+      # although the LINE API typically expects an array of message objects,
+      # which this container helps to build.
+      #
+      # Each message added to the container can also have its own quick reply.
+      #
+      # @example Building multiple messages
+      #   message_payload = Line::Message::Builder.with do
+      #     text "Hello, this is the first message!"
+      #     flex alt_text: "This is a Flex Message" do
+      #       bubble do
+      #         body do
+      #           body.text "This is a Flex Message body."
+      #         end
+      #       end
+      #     end
+      #   end.build # => Returns an array of message hashes
+      #
+      # @see Base
+      # @see Text
+      # @see Flex::Builder
+      # @see QuickReply
+      class Container
+        # @!attribute [r] context
+        #   @return [Context] The context object, which can hold external data or
+        #     helper methods accessible within the builder blocks.
         attr_reader :context
 
-        def initialize(context: nil, &)
-          @messages = []
+        # Initializes a new message container.
+        # This is typically not called directly but through `Line::Message::Builder.with`.
+        # The provided block is instance-eval'd, allowing DSL methods like
+        # {#text} and {#flex} to be called directly on the container instance.
+        #
+        # @param context [Object, nil] An optional context object that can be used
+        #   to share data or helper methods within the builder block. It's wrapped
+        #   in a {Context} object.
+        # @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.
+        # @param block [Proc] A block containing DSL calls to define messages
+        #   (e.g., `text "Hello"`, `flex { ... }`).
+        def initialize(context: nil, mode: :api, &block)
+          @messages = [] # Initializes an empty array to store message objects
+          @context = Context.new(context, mode:)
 
-          super
+          instance_eval(&block) if ::Kernel.block_given?
         end
 
+        # Creates a new {Text} message and adds it to this container.
+        #
+        # @param text [String] The text content of the message.
+        # @param options [Hash] Additional options for the text message,
+        #   such as `:quick_reply`. See {Text#initialize}.
+        # @param block [Proc, nil] An optional block that will be instance-eval'd
+        #   in the context of the new {Text} message instance. This can be used
+        #   to add a quick reply to the text message.
+        # @return [Text] The newly created {Text} message object.
+        #
+        # @example
+        #   root.text "Hello, world!" do
+        #     quick_reply do
+        #       button action: :message, label: "Hi!", text: "Hi!"
+        #     end
+        #   end
         def text(text, **options, &)
           @messages << Text.new(text, context: context, **options, &)
         end
 
+        # Creates a new {Flex::Builder} for constructing a Flex Message and adds it
+        # to this container. The block is mandatory and is used to define the
+        # content of the Flex Message using the Flex Message DSL.
+        #
+        # @param options [Hash] Options for the Flex Message, primarily `:alt_text`.
+        #   See {Flex::Builder#initialize}. It's important to provide `alt_text`.
+        # @param block [Proc] A block that will be instance-eval'd in the context
+        #   of the new {Flex::Builder} instance. This block is used to define the
+        #   structure and content of the Flex Message (e.g., bubbles, carousels).
+        # @return [Flex::Builder] The newly created {Flex::Builder} object.
+        # @raise [ArgumentError] if `alt_text` is not provided in options (validation
+        #   is typically within Flex::Builder).
+        #
+        # @example
+        #   flex alt_text: "Important information" do
+        #     bubble do
+        #       header { text "Header" }
+        #       body   { text "Body" }
+        #     end
+        #   end
         def flex(**options, &)
           @messages << Flex::Builder.new(context: context, **options, &)
         end
 
+        # Converts all messages held by this container into their hash representations.
+        # This method iterates over each message object (e.g., {Text}, {Flex::Builder})
+        # stored in the container and calls its `to_h` method. The result is an
+        # array of hashes, where each hash represents a single LINE message object
+        # ready for JSON serialization and sending to the LINE Messaging API.
+        #
+        # @return [Array<Hash>] An array of message objects, each represented as a hash.
+        #   This is the format expected by the LINE API for the `messages` field
+        #   in a request body.
         def build
           @messages.map(&:to_h)
         end
 
+        # Converts the array of message hashes (obtained from {#build}) into a
+        # JSON string. This is a convenience method for serializing the messages
+        # payload.
+        #
+        # @param args [Object] Optional arguments that are passed along to `to_json`
+        #   method of the underlying array.
+        # @return [String] A JSON string representing the array of message objects.
         def to_json(*args)
           build.to_json(*args)
         end
+
+        # Checks if a method is defined in the context object.
+        # This is part of Ruby's method_missing mechanism.
+        #
+        # @param method_name [Symbol] The name of the method being checked
+        # @param include_private [Boolean] Whether to include private methods
+        # @return [Boolean] True if the method exists in the context, false otherwise
+        def respond_to_missing?(method_name, include_private = false)
+          context.respond_to?(method_name, include_private) || super
+        end
+
+        # Delegates method calls to the context object if they exist there.
+        # This allows helper methods defined in the context to be called directly
+        # from within the builder DSL.
+        #
+        # @param method_name [Symbol] The name of the method being called
+        # @param args [Array] The arguments passed to the method
+        # @return [Object] The result of calling the method on the context
+        # @raise [NoMethodError] If the method doesn't exist in the context
+        def method_missing(method_name, ...)
+          return context.send(method_name, ...) if context.respond_to?(method_name)
+
+          super
+        end
       end
     end
   end

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

@@ -3,27 +3,135 @@
 module Line
   module Message
     module Builder
-      # The context is wrapper for the context object to provide assigns support.
+      # The `Context` class is a crucial component of the `Line::Message::Builder`
+      # DSL, enabling a flexible and dynamic environment for message construction.
+      # It acts as a wrapper around an optional user-provided context object and
+      # manages a separate hash of "assigns" (local variables for the DSL).
+      #
+      # The primary purposes of the `Context` are:
+      # 1.  **To provide access to helper methods**: If a user passes a context object
+      #     (e.g., a Rails view context, a presenter, or any custom object) during
+      #     builder initialization (`Line::Message::Builder.with(my_helper_object)`),
+      #     methods defined on `my_helper_object` become directly callable within
+      #     the DSL blocks.
+      # 2.  **To allow local data storage (`assigns`)**: The `assigns` hash allows
+      #     for setting and retrieving temporary data that can be shared across
+      #     different parts of a complex message construction block, without needing
+      #     to pass it explicitly or pollute the user-provided context.
+      #
+      # Method calls within the DSL that are not defined on the builder objects
+      # themselves are resolved by `Context` in the following order:
+      # - First, it checks if the method name corresponds to a key in the `assigns` hash.
+      # - If not found in `assigns`, it checks if the wrapped user-context object
+      #   responds to the method.
+      # - If neither, the call proceeds up the normal Ruby method lookup chain.
+      #
+      # This mechanism allows for a clean and powerful way to integrate external logic
+      # and data into the message building process.
+      #
+      # @example Using a custom context
+      #   class MyContext
+      #     def current_user_name
+      #       "Alice"
+      #     end
+      #   end
+      #
+      #   context = MyContext.new
+      #   Line::Message::Builder.with(context) do
+      #     # `current_user_name` is resolved from `context` by Context
+      #     text "Hello, #{current_user_name}!"
+      #   end
       class Context
+        # @!attribute assigns
+        #   A hash for storing arbitrary data that can be accessed within the
+        #   builder DSL. This is useful for temporary variables or shared state
+        #   during message construction.
+        #   @return [Hash] The hash of assigned values.
+        #   @example
+        #     context.assigns[:user_id] = 123
+        #     puts context.assigns[:user_id] # => 123
         attr_accessor :assigns
 
-        def initialize(context)
+        # @!attribute [r] mode
+        #   The mode in which the builder is operating. This affects how messages
+        #   are formatted in the final output.
+        #   @return [Symbol] Either `:api` for direct LINE Messaging API format
+        #     or `:sdkv2` for LINE Bot SDK v2 compatible format.
+        attr_reader :mode
+
+        # Initializes a new Context object.
+        #
+        # @param context [Object, nil] An optional object whose methods will be made
+        #   available within the DSL. If `nil`, only `assigns` and standard
+        #   builder methods will be available.
+        # @param mode [Symbol] The mode of the context, which can be `:api` (default)
+        #   for direct LINE Messaging API format or `:sdkv2` for LINE Bot SDK v2
+        #   compatible format.
+        def initialize(context, mode: :api)
           @context = context
           @assigns = {}
+          @mode = mode
         end
 
+        # Part of Ruby's dynamic method dispatch. It's overridden here to declare
+        # that instances of `Context` can respond to methods that are either:
+        # 1. Keys in the `@assigns` hash.
+        # 2. Methods to which the wrapped `@context` object responds.
+        #
+        # This ensures that `respond_to?` behaves consistently with how
+        # `method_missing` resolves method calls.
+        #
+        # @param method_name [Symbol] The name of the method being queried.
+        # @param include_private [Boolean] Whether to include private methods in
+        #   the check.
+        # @return [Boolean] `true` if the context can handle the method,
+        #   `false` otherwise.
+        # @!visibility private
         def respond_to_missing?(method_name, include_private = false)
           @assigns.key?(method_name) ||
-            @context.respond_to?(method_name, include_private) ||
+            @context.respond_to?(method_name, include_private) || # Check @context directly
             super
         end
 
+        # Handles calls to methods not explicitly defined on the `Context` class.
+        # The resolution order is:
+        # 1.  If `method_name` is a key in the `@assigns` hash, its value is returned.
+        # 2.  If the wrapped `@context` object responds to `method_name`, the call
+        #     is delegated to `@context`.
+        # 3.  Otherwise, `super` is called, allowing the standard Ruby method
+        #     lookup to continue (which will likely result in a `NoMethodError`
+        #     if the method is truly undefined).
+        #
+        # This is the core mechanism that allows DSL blocks to seamlessly access
+        # data from `assigns` or methods from the user-provided context.
+        #
+        # @param method_name [Symbol] The name of the invoked method.
+        # @param ... [Object] Arguments passed to the method.
+        # @return [Object, nil] The value from `@assigns`, the result of the
+        #   delegated call to `@context`, or raises `NoMethodError` via `super`.
+        # @raise [NoMethodError] If the method is not found in `assigns` or
+        #   on the wrapped context.
+        # @!visibility private
         def method_missing(method_name, ...)
           return @assigns[method_name] if @assigns.key?(method_name)
+          # Check @context directly
           return @context.public_send(method_name, ...) if @context.respond_to?(method_name)
 
           super
         end
+
+        # Checks if the current mode is set to SDK v2 compatibility.
+        #
+        # @return [Boolean] `true` if the mode is `:sdkv2`, `false` otherwise.
+        # @example
+        #   if context.sdkv2?
+        #     # Format message for LINE Bot SDK v2
+        #   else
+        #     # Format message for direct API use
+        #   end
+        def sdkv2?
+          mode == :sdkv2
+        end
       end
     end
   end

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

@@ -4,16 +4,61 @@ module Line
   module Message
     module Builder
       module Flex
-        # The action DSL for flex components.
+        # The `Actionable` module provides a DSL for defining an action that can be
+        # triggered when a user interacts with certain Flex Message components
+        # (e.g., a {Button} component, or an entire {Bubble} or {Box} component
+        # if it's made tappable).
+        #
+        # When a component includes this module, it gains methods like {#message}
+        # and {#postback} to associate a specific LINE action with itself. The
+        # chosen action is stored in the `action` attribute.
+        #
+        # @!attribute [r] action
+        #   @return [Actions::Message, Actions::Postback, nil] The action object
+        #     associated with this component. `nil` if no action is defined.
+        #
+        # @see Line::Message::Builder::Actions::Message
+        # @see Line::Message::Builder::Actions::Postback
+        # @see https://developers.line.biz/en/reference/messaging-api/#action-objects
         module Actionable
+          # @!visibility private
+          # Automatically adds an `attr_reader :action` to the class that includes
+          # this module.
+          # @param base [Class] The class including this module.
           def self.included(base)
             base.attr_reader :action
           end
 
+          # Defines a message action for the component.
+          # When the component is tapped, a message with the given `text` is sent
+          # from the user to the chat.
+          #
+          # @param text [String] The text of the message to send.
+          # @param options [Hash] Additional options for the message action,
+          #   such as `:label`. See {Actions::Message#initialize}.
+          # @param block [Proc, nil] An optional block, though not typically used
+          #   directly for message actions here.
+          # @return [Actions::Message] The created message action object.
+          #
+          # @example Setting a message action on a button
+          #   button_component.message "Hello User!", label: "Send Greeting"
           def message(text, **options, &)
             @action = Actions::Message.new(text, context: context, **options, &)
           end
 
+          # Defines a postback action for the component.
+          # When the component is tapped, a postback event with the given `data`
+          # is sent to the bot's webhook.
+          #
+          # @param data [String] The data payload for the postback event.
+          # @param options [Hash] Additional options for the postback action,
+          #   such as `:label` or `:display_text`. See {Actions::Postback#initialize}.
+          # @param block [Proc, nil] An optional block, though not typically used
+          #   directly for postback actions here.
+          # @return [Actions::Postback] The created postback action object.
+          #
+          # @example Setting a postback action on a button
+          #   button_component.postback "action=buy&item_id=123", label: "Buy Item"
           def postback(data, **options, &)
             @action = Actions::Postback.new(data, context: context, **options, &)
           end

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

@@ -4,66 +4,206 @@ module Line
   module Message
     module Builder
       module Flex
-        # The box is a component for the Flex message.
+        # Represents a "box" component in a LINE Flex Message.
+        #
+        # A box is a fundamental layout container that arranges its child components
+        # (`contents`) in a specified direction (`layout`: horizontal, vertical, or
+        # baseline). It can hold various other components like text, images, buttons,
+        # or even nested boxes, allowing for complex layouts.
+        #
+        # Boxes have numerous properties to control their appearance and the
+        # arrangement of their children, such as padding, margin, spacing between
+        # items, justification, and alignment.
+        #
+        # A box can also have an `action` associated with it, making the entire
+        # box area tappable.
+        #
+        # @example Creating a horizontal box with two text components
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Box example" do
+        #       bubble do
+        #         body do
+        #           layout :horizontal
+        #           spacing :md
+        #           text "Item 1"
+        #           text "Item 2"
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#box
+        # @see Actionable For making the box tappable.
+        # @see HasPartial For including reusable component groups.
+        # @see Position::Padding For padding properties.
+        # @see Position::Margin For margin properties.
+        # @see Position::Offset For offset properties.
+        # @see Size::Flex For flex sizing property.
         class Box < Line::Message::Builder::Base
-          include HasPartial
-          include Actionable
-          include Position::Padding
-          include Position::Margin
-          include Position::Offset
-          include Size::Flex
+          include HasPartial # Allows including predefined partial component sets.
+          include Actionable # Enables defining an action for the entire box.
+          include Position::Padding  # Adds padding options like `padding_all`, `padding_top`, etc.
+          include Position::Margin   # Adds `margin` option.
+          include Position::Offset   # Adds offset options like `offset_top`, `offset_start`, etc.
+          include Size::Flex         # Adds `flex` option for controlling size within a parent box.
 
+          # @!attribute [r] contents
+          #   @return [Array<Base>] An array holding the child components (e.g.,
+          #     {Text}, {Image}, nested {Box} instances) of this box.
           attr_reader :contents
 
+          # Specifies the arrangement of child components.
+          # @!method layout(value)
+          #   @param value [Symbol] `:horizontal` (default), `:vertical`, or `:baseline`.
+          #   @return [Symbol] The current layout.
           option :layout, default: :horizontal, validator: Validators::Enum.new(
             :horizontal, :vertical, :baseline
           )
+
+          # Horizontal alignment of content in a horizontal box; vertical alignment in a vertical box.
+          # @!method justify_content(value)
+          #   @param value [Symbol, nil] E.g., `:flex_start`, `:center`, `:flex_end`,
+          #     `:space_between`, `:space_around`, `:space_evenly`.
+          #   @return [Symbol, nil] The current justify_content value.
           option :justify_content, default: nil, validator: Validators::Enum.new(
             :flex_start, :center, :flex_end, :space_between, :space_around, :space_evenly
           )
+
+          # Vertical alignment of content in a horizontal box; horizontal alignment in a vertical box.
+          # @!method align_items(value)
+          #   @param value [Symbol, nil] E.g., `:flex_start`, `:center`, `:flex_end`.
+          #   @return [Symbol, nil] The current align_items value.
           option :align_items, default: nil, validator: Validators::Enum.new(
             :flex_start, :center, :flex_end
           )
+
+          # Specifies the minimum spacing between components.
+          # Not applicable if `layout` is `:baseline` or if the box contains only one component.
+          # @!method spacing(value)
+          #   @param value [String, Symbol, nil] E.g., `"md"`, `:lg`, `"10px"`.
+          #     Keywords: `:none`, `:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:xxl`.
+          #   @return [String, Symbol, nil] The current spacing value.
           option :spacing, default: nil, validator: Validators::Size.new(:pixel, :keyword)
+
+          # Width of the box. Can be a percentage or pixel value.
+          # @!method width(value)
+          #   @param value [String, nil] E.g., `"100px"`, `"50%"`.
+          #   @return [String, nil] The current width.
           option :width, default: nil, validator: Validators::Size.new(:pixel, :percentage)
+
+          # Maximum width of the box.
+          # @!method max_width(value)
+          #   @param value [String, nil] E.g., `"100px"`, `"50%"`.
+          #   @return [String, nil] The current maximum width.
           option :max_width, default: nil, validator: Validators::Size.new(:pixel, :percentage)
+
+          # Height of the box.
+          # @!method height(value)
+          #   @param value [String, nil] E.g., `"100px"`, `"50%"`.
+          #   @return [String, nil] The current height.
           option :height, default: nil, validator: Validators::Size.new(:pixel, :percentage)
+
+          # Maximum height of the box.
+          # @!method max_height(value)
+          #   @param value [String, nil] E.g., `"100px"`, `"50%"`.
+          #   @return [String, nil] The current maximum height.
           option :max_height, default: nil, validator: Validators::Size.new(:pixel, :percentage)
 
+          # Initializes a new Flex Message Box component.
+          # The provided block is instance-eval'd, allowing DSL methods for adding
+          # child components (e.g., {#text}, {#button}, nested {#box}) to be called.
+          #
+          # @param context [Object, nil] An optional context for the builder.
+          # @param options [Hash] A hash of options to set instance variables.
+          #   Corresponds to the `option` definitions in this class and included modules.
+          # @param block [Proc, nil] A block to define the contents of this box.
           def initialize(context: nil, **options, &)
-            @contents = []
-
-            super
+            @contents = [] # Holds child components
+            super # Calls Base#initialize, sets options, and evals block
           end
 
+          # Adds a nested Flex {Box} component to this box's contents.
+          #
+          # @param options [Hash] Options for the nested box. See {Box#initialize}.
+          # @param block [Proc] A block to define the contents of the nested box.
+          # @return [Flex::Box] The newly created nested Box object.
           def box(**options, &)
             @contents << Flex::Box.new(context: context, **options, &)
           end
 
-          def text(text, **options, &)
+          # Adds a Flex {Text} component to this box's contents.
+          #
+          # @param text [String] The text content.
+          # @param options [Hash] Options for the text component. See {Text#initialize}.
+          # @param block [Proc, nil] An optional block for the text component. This can be used
+          #   to define an action for the text or to add {Span} components within the text.
+          # @return [Flex::Text] The newly created Text object.
+          # @example Simple text component
+          #   text "Hello, World!"
+          # @example Text with an action
+          #   text "Click me" do
+          #     message "Action", text: "You clicked me!"
+          #   end
+          # @example Text with spans
+          #   text "This has " do
+          #     span "styled", color: "#FF0000"
+          #     span " parts"
+          #   end
+          def text(text = nil, **options, &)
             @contents << Flex::Text.new(text, context: context, **options, &)
           end
 
+          # Adds a Flex {Button} component to this box's contents.
+          #
+          # @param options [Hash] Options for the button component. See {Button#initialize}.
+          # @param block [Proc] A block to define the button's action and properties.
+          # @return [Flex::Button] The newly created Button object.
           def button(**options, &)
             @contents << Flex::Button.new(context: context, **options, &)
           end
 
+          # Adds a Flex {Image} component to this box's contents.
+          #
+          # @param url [String] The URL of the image.
+          # @param options [Hash] Options for the image component. See {Image#initialize}.
+          # @param block [Proc, nil] An optional block for the image component (e.g., for an action).
+          # @return [Flex::Image] The newly created Image object.
           def image(url, **options, &)
             @contents << Flex::Image.new(url, context: context, **options, &)
           end
 
-          def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+          # Adds a Flex {Separator} component to this box's contents.
+          #
+          # A separator is a simple component that draws a horizontal line,
+          # creating a visual division between other components in a container.
+          #
+          # @param options [Hash] Options for the separator component. See {Separator}.
+          # @param block [Proc, nil] An optional block for advanced separator configuration.
+          # @return [Flex::Separator] The newly created Separator object.
+          def separator(**options, &)
+            @contents << Flex::Separator.new(context: context, **options, &)
+          end
+
+          def to_h
             raise RequiredError, "layout is required" if layout.nil?
 
+            return to_sdkv2 if context.sdkv2?
+
+            to_api
+          end
+
+          private
+
+          def to_api # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             {
               type: "box",
               layout: layout,
-              # Position
+              # Position & Layout
               justifyContent: justify_content,
               alignItems: align_items,
               spacing: spacing,
               # Position::Padding
-              paddingAll: padding,
+              paddingAll: padding || padding_all,
               paddingTop: padding_top,
               paddingBottom: padding_bottom,
               paddingStart: padding_start,
@@ -83,8 +223,44 @@ module Line
               maxHeight: max_height,
               # Size::Flex
               flex: flex,
+              # Contents & Action
+              contents: contents.map(&:to_h),
+              action: action&.to_h # From Actionable module
+            }.compact
+          end
+
+          def to_sdkv2 # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            {
+              type: "box",
+              layout: layout,
+              # Position & Layout
+              justify_content: justify_content,
+              align_items: align_items,
+              spacing: spacing,
+              # Position::Padding
+              padding_all: padding || padding_all,
+              padding_top: padding_top,
+              padding_bottom: padding_bottom,
+              padding_start: padding_start,
+              padding_end: padding_end,
+              # 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
+              width: width,
+              max_width: max_width,
+              height: height,
+              max_height: max_height,
+              # Size::Flex
+              flex: flex,
+              # Contents & Action
               contents: contents.map(&:to_h),
-              action: action&.to_h
+              action: action&.to_h # From Actionable module
             }.compact
           end
         end