line-message-builder 0.7.0 → 0.8.0

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

@@ -3,27 +3,139 @@
 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 MyHelpers
+      #     def current_user_name
+      #       "Alice"
+      #     end
+      #   end
+      #
+      #   helpers = MyHelpers.new
+      #   Line::Message::Builder.with(helpers) do |root|
+      #     # `current_user_name` is resolved from `helpers` by Context
+      #     root.text "Hello, #{current_user_name}!"
+      #
+      #     # Using assigns
+      #     assigns[:item_count] = 5
+      #     root.text "You have #{assigns[:item_count]} items."
+      #   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,182 @@ 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 |root|
+        #     root.flex alt_text: "Box example" do |flex|
+        #       flex.bubble do |bubble|
+        #         bubble.body do |body_box| # body_box is an instance of Flex::Box
+        #           body_box.layout :horizontal
+        #           body_box.spacing :md
+        #           body_box.text "Item 1"
+        #           body_box.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
 
+          # 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 (e.g., for an action).
+          # @return [Flex::Text] The newly created Text object.
           def text(text, **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
+          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 +199,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

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

@@ -4,51 +4,139 @@ module Line
   module Message
     module Builder
       module Flex
-        # The bubble is container for the Flex message.
+        # Represents a "bubble" container in a LINE Flex Message.
+        # A bubble is a self-contained unit of content, structured into optional
+        # sections: header, hero (an image or box), body, and footer.
+        # Bubbles are the fundamental building blocks for single Flex Messages or
+        # for each item in a {Carousel} container.
+        #
+        # @example Creating a simple bubble with a body
+        #   Line::Message::Builder.with do |root|
+        #     root.flex alt_text: "Simple Bubble" do |flex|
+        #       flex.bubble do |bubble|
+        #         bubble.body do |body_box|
+        #           body_box.text "Hello, this is a bubble!"
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#bubble
+        # @see HasPartial For including reusable component groups within sections.
+        # @see Box For the structure of header, hero (if box), body, and footer.
+        # @see Image For using an image as a hero section.
         class Bubble < Line::Message::Builder::Base
-          include HasPartial
+          include HasPartial # Allows including predefined partial component sets into sections.
 
-          option :size, default: nil
+          # Specifies the size of the bubble.
+          # @!method size(value)
+          #   @param value [Symbol, String, nil] Bubble size. Keywords: `:nano`, `:micro`,
+          #     `:kilo`, `:mega`, `:giga`. Pixel/percentage values are not directly
+          #     supported for bubble size by LINE; use keywords.
+          #   @return [Symbol, String, nil] The current bubble size.
+          option :size, default: nil # E.g., :nano, :micro, :kilo, :mega, :giga
+
+          # Defines custom styles for the bubble and its sections (header, hero, body, footer).
+          # @!method styles(value)
+          #   @param value [Hash, nil] A hash defining style overrides.
+          #     See LINE API documentation for the structure of the styles object.
+          #   @return [Hash, nil] The current styles hash.
+          #   @example
+          #     bubble.styles(
+          #       header: { backgroundColor: "#FF0000" },
+          #       body: { separator: true, separatorColor: "#00FF00" }
+          #     )
           option :styles, default: nil
 
+          # Initializes a new Flex Message Bubble container.
+          # The provided block is instance-eval'd, allowing DSL methods for defining
+          # sections (e.g., {#header}, {#body}) to be called.
+          #
+          # @param context [Object, nil] An optional context for the builder.
+          # @param options [Hash] A hash of options to set instance variables
+          #   (e.g., `:size`, `:styles`).
+          # @param block [Proc, nil] A block to define the sections of this bubble.
           def initialize(context: nil, **options, &)
             @header = nil
             @hero = nil
             @body = nil
             @footer = nil
 
-            super
+            super # Calls Base#initialize, sets options, and evals block
           end
 
+          # Defines the header section of the bubble using a {Box} component.
+          #
+          # @param options [Hash] Options for the header Box. See {Box#initialize}.
+          # @param block [Proc] A block to define the contents of the header Box.
+          # @return [Flex::Box] The newly created Box object for the header.
           def header(**options, &)
             @header = Box.new(**options, context: context, &)
           end
 
+          # Defines the hero section of the bubble using a {Box} component.
+          # The hero section is typically used for prominent content like a large image or video.
+          #
+          # @param options [Hash] Options for the hero Box. See {Box#initialize}.
+          # @param block [Proc] A block to define the contents of the hero Box.
+          # @return [Flex::Box] The newly created Box object for the hero section.
           def hero(**options, &)
             @hero = Box.new(**options, context: context, &)
           end
 
+          # Defines the hero section of the bubble using an {Image} component.
+          # This is a convenience method for common cases where the hero is a single image.
+          #
+          # @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 for the hero section.
           def hero_image(url, **options, &)
             @hero = Image.new(url, **options, context: context, &)
           end
 
+          # Defines the body section of the bubble using a {Box} component.
+          # This is the main content area of the bubble.
+          #
+          # @param options [Hash] Options for the body Box. See {Box#initialize}.
+          # @param block [Proc] A block to define the contents of the body Box.
+          # @return [Flex::Box] The newly created Box object for the body.
           def body(**options, &)
             @body = Box.new(**options, context: context, &)
           end
 
+          # Defines the footer section of the bubble using a {Box} component.
+          #
+          # @param options [Hash] Options for the footer Box. See {Box#initialize}.
+          # @param block [Proc] A block to define the contents of the footer Box.
+          # @return [Flex::Box] The newly created Box object for the footer.
           def footer(**options, &)
             @footer = Box.new(**options, context: context, &)
           end
 
-          def to_h
+          private
+
+          def to_api
+            {
+              type: "bubble",
+              size: size, # From option
+              styles: styles, # From option
+              header: @header&.to_h,
+              hero: @hero&.to_h,
+              body: @body&.to_h,
+              footer: @footer&.to_h
+            }.compact
+          end
+
+          def to_sdkv2
             {
               type: "bubble",
+              size: size, # From option
+              styles: styles, # From option
               header: @header&.to_h,
               hero: @hero&.to_h,
               body: @body&.to_h,
-              footer: @footer&.to_h,
-              size: size,
-              styles: styles
+              footer: @footer&.to_h
             }.compact
           end
         end