line-message-builder 0.7.0 → 0.8.0

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

@@ -4,32 +4,98 @@ module Line
   module Message
     module Builder
       module Flex
-        # The Builder class is used to build quick reply buttons.
+        # The `Builder` class is the main entry point for constructing a complete
+        # LINE Flex Message. A Flex Message is a highly customizable message type
+        # that can contain one main content element, which is either a single
+        # {Bubble} or a {Carousel} of bubbles.
+        #
+        # This builder requires `alt_text` (alternative text) for accessibility and
+        # for display on devices or LINE versions that cannot render Flex Messages.
+        # It can also have a `quickReply` attached to it.
+        #
+        # @example Creating a Flex Message with a single bubble
+        #   Line::Message::Builder.with do |root|
+        #     root.flex alt_text: "My Product" do |flex_builder| # flex_builder is an instance of Flex::Builder
+        #       flex_builder.bubble size: :giga do |bubble_content|
+        #         bubble_content.hero_image "https://example.com/product.jpg"
+        #         bubble_content.body do |b|
+        #           b.text "Product Name", weight: :bold, size: :xl
+        #         end
+        #       end
+        #       flex_builder.quick_reply do |qr|
+        #         qr.button action: :message, label: "Learn More", text: "Tell me more"
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#flex-messages
+        # @see Bubble
+        # @see Carousel
+        # @see QuickReply
         class Builder < Line::Message::Builder::Base
+          # Alternative text for the Flex Message. Displayed on devices that
+          # cannot render Flex Messages or used for accessibility.
+          # This is a required field for a valid Flex Message.
+          # @!method alt_text(value)
+          #   @param value [String, nil] The alternative text. Max 400 characters.
+          #   @return [String, nil] The current alternative text.
           option :alt_text, default: nil
 
+          # Initializes a new Flex Message Builder.
+          # The provided block is instance-eval'd, allowing DSL methods like
+          # {#bubble} or {#carousel} to define the main content.
+          #
+          # @param context [Object, nil] An optional context for the builder.
+          # @param options [Hash] A hash of options to set instance variables (e.g., `:alt_text`).
+          # @param block [Proc, nil] A block to define the content (bubble or carousel)
+          #   of this Flex Message.
           def initialize(context: nil, **options, &)
-            @contents = nil
+            @contents = nil # Will hold either a Bubble or Carousel instance
 
-            super
+            super # Calls Base#initialize, sets options (like @alt_text), and evals block
           end
 
+          # Defines the content of this Flex Message as a single {Bubble}.
+          # If called, this will overwrite any previously defined `carousel` content.
+          #
+          # @param options [Hash] Options for the Bubble. See {Bubble#initialize}.
+          # @param block [Proc] A block to define the sections of the Bubble.
+          # @return [Flex::Bubble] The newly created Bubble object.
           def bubble(**options, &)
             @contents = Line::Message::Builder::Flex::Bubble.new(context: context, **options, &)
           end
 
+          # Defines the content of this Flex Message as a {Carousel} of bubbles.
+          # If called, this will overwrite any previously defined `bubble` content.
+          #
+          # @param options [Hash] Options for the Carousel. See {Carousel#initialize}.
+          # @param block [Proc] A block to define the bubbles within the Carousel.
+          # @return [Flex::Carousel] The newly created Carousel object.
           def carousel(**options, &)
             @contents = Line::Message::Builder::Flex::Carousel.new(context: context, **options, &)
           end
 
-          def to_h
-            raise Error, "contents should be bubble or carousel" if @contents.nil?
+          private
+
+          def to_api
+            raise Error, "Flex Message contents (bubble or carousel) must be defined." if @contents.nil?
+
+            {
+              type: "flex",
+              altText: alt_text, # From option
+              contents: @contents.to_h, # Serializes the Bubble or Carousel
+              quickReply: @quick_reply&.to_h # From Base class's quick_reply method
+            }.compact
+          end
+
+          def to_sdkv2
+            raise Error, "Flex Message contents (bubble or carousel) must be defined." if @contents.nil?
 
             {
               type: "flex",
-              altText: @alt_text,
-              contents: @contents.to_h,
-              quickReply: @quick_reply&.to_h
+              alt_text: alt_text, # From option
+              contents: @contents.to_h, # Serializes the Bubble or Carousel
+              quick_reply: @quick_reply&.to_h # From Base class's quick_reply method
             }.compact
           end
         end

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

@@ -4,30 +4,87 @@ module Line
   module Message
     module Builder
       module Flex
-        # The button is a component of the Flex message.
+        # Represents a "button" component in a LINE Flex Message.
+        #
+        # Buttons are interactive elements that users can tap to trigger an {Actionable#action action}
+        # (e.g., open a URL, send a message, or trigger a postback). They have
+        # various styling options, including `style` (primary, secondary, link) and
+        # `height`.
+        #
+        # An action is mandatory for a button component.
+        #
+        # @example Creating a button that sends a message
+        #   Line::Message::Builder.with do |root|
+        #     root.flex alt_text: "Button Example" do |flex|
+        #       flex.bubble do |bubble|
+        #         bubble.body do |body_box|
+        #           body_box.button style: :primary, height: :sm do |btn|
+        #             btn.message "Buy Now", label: "Buy" # Action definition
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#button
+        # @see Actionable For defining the button's action (mandatory).
+        # @see Position::Vertical For `gravity` property.
+        # @see Position::Padding For padding properties.
+        # @see Position::Margin For margin property.
+        # @see Position::Offset For offset properties.
+        # @see Size::Flex For flex sizing property.
+        # @see Size::AdjustMode For `adjust_mode` property.
         class Button < Line::Message::Builder::Base
-          include Actionable
-          include Position::Vertical
-          include Position::Padding
-          include Position::Margin
-          include Position::Offset
-          include Size::Flex
-          include Size::AdjustMode
+          include Actionable # Defines the action performed when the button is tapped.
+          include Position::Vertical # Adds `gravity` option for vertical alignment.
+          include Position::Padding  # Adds padding options.
+          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::AdjustMode   # Adds `adjust_mode` option.
 
+          # Specifies the style of the button.
+          # @!method style(value)
+          #   @param value [Symbol, String] Button style.
+          #     Can be `:primary`, `:secondary`, `:link` (default).
+          #     String values should match these keywords.
+          #   @return [Symbol, String] The current button style.
           option :style, default: :link
+
+          # Specifies the height of the button.
+          # @!method height(value)
+          #   @param value [Symbol, String] Button height.
+          #     Can be `:sm` (small) or `:md` (medium, default).
+          #   @return [Symbol, String] The current button height.
           option :height, default: :md, validator: Validators::Enum.new(:sm, :md)
 
-          def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-            raise RequiredError, "action is required" if action.nil?
+          # Initializes a new Flex Message Button component.
+          # The provided block is instance-eval'd, primarily used to define the
+          # button's action using methods from the {Actionable} module (e.g., `message "label"`).
+          #
+          # @param context [Object, nil] An optional context for the builder.
+          # @param options [Hash] A hash of options to set instance variables
+          #   (e.g., `:style`, `:height`, and options from included modules).
+          # @param block [Proc, nil] A block to define the button's action and other properties.
+          #   This block is where you should call an action method like `message` or `postback`.
+          def initialize(context: nil, **options, &)
+            super # Calls Base#initialize, sets options, and evals block (which should define the action)
+          end
+
+          private
+
+          def to_api # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            raise RequiredError, "action is required for a button" if action.nil?
 
             {
               type: "button",
-              action: action.to_h,
-              height: height,
-              # Position
-              grivity: gravity,
+              action: action.to_h, # From Actionable module
+              style: style,         # From option
+              height: height,       # From option
+              # Position::Vertical
+              gravity: gravity,
               # Position::Padding
-              paddingAll: padding,
+              paddingAll: padding || padding_all,
               paddingTop: padding_top,
               paddingBottom: padding_bottom,
               paddingStart: padding_start,
@@ -43,8 +100,38 @@ module Line
               # Size::Flex
               flex: flex,
               # Size::AdjustMode
-              adjustMode: adjust_mode,
-              style: style
+              adjustMode: adjust_mode
+            }.compact
+          end
+
+          def to_sdkv2 # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            raise RequiredError, "action is required for a button" if action.nil?
+
+            {
+              type: "button",
+              action: action.to_h, # From Actionable module
+              style: style,         # From option
+              height: height,       # From option
+              # Position::Vertical
+              gravity: gravity,
+              # 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::Flex
+              flex: flex,
+              # Size::AdjustMode
+              adjust_mode: adjust_mode
             }.compact
           end
         end

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

@@ -4,28 +4,91 @@ module Line
   module Message
     module Builder
       module Flex
-        # The carousel is multiple bubbles in a single Flex message.
+        # Represents a "carousel" container in a LINE Flex Message.
+        # A carousel is a horizontally scrollable sequence of {Bubble} components.
+        # Each bubble in the carousel is a distinct message unit. Users can swipe
+        # left or right to view the different bubbles.
+        #
+        # Carousels are ideal for presenting multiple items, such as products,
+        # articles, or options, in a compact and interactive way.
+        #
+        # @example Creating a carousel with two bubbles
+        #   Line::Message::Builder.with do |root|
+        #     root.flex alt_text: "Product Showcase" do |flex_builder|
+        #       flex_builder.carousel do |carousel_container| # carousel_container is an instance of Flex::Carousel
+        #         carousel_container.bubble size: :mega do |bubble1|
+        #           bubble1.hero_image "https://example.com/product1.jpg"
+        #           bubble1.body { |b| b.text "Product 1" }
+        #         end
+        #         carousel_container.bubble size: :mega do |bubble2|
+        #           bubble2.hero_image "https://example.com/product2.jpg"
+        #           bubble2.body { |b| b.text "Product 2" }
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#carousel
+        # @see Bubble For the structure of individual items within the carousel.
+        # @see HasPartial While included, direct usage on Carousel itself is limited;
+        #   partials are more commonly used within the individual bubbles.
         class Carousel < Line::Message::Builder::Base
-          include HasPartial
+          include HasPartial # Allows including predefined partial component sets (more relevant for bubbles within).
 
+          # @!attribute [r] contents
+          #   @return [Array<Flex::Bubble>] An array holding the {Bubble} components
+          #     that form the items of this carousel.
+          attr_reader :contents
+
+          # Initializes a new Flex Message Carousel container.
+          # The provided block is instance-eval'd, allowing DSL methods like
+          # {#bubble} to be called to add bubbles to the carousel.
+          #
+          # @param context [Object, nil] An optional context for the builder.
+          # @param options [Hash] A hash of options (currently none specific to Carousel itself,
+          #   but available for future extensions or via `Base`).
+          # @param block [Proc, nil] A block to define the bubbles within this carousel.
           def initialize(context: nil, **options, &)
-            @contents = []
+            @contents = [] # Holds an array of Bubble objects
 
-            super
+            super # Calls Base#initialize, sets options, and evals block
           end
 
+          # Adds a new {Bubble} to this carousel's contents.
+          # Each call to this method appends another bubble to the horizontal sequence.
+          #
+          # @param options [Hash] Options for the Bubble. See {Bubble#initialize}.
+          # @param block [Proc] A block to define the sections and content of the Bubble.
+          # @return [Flex::Bubble] The newly created Bubble object that was added to the carousel.
           def bubble(**options, &)
+            # The maximum number of bubbles is validated in `to_h` as per LINE API limits.
             @contents << Line::Message::Builder::Flex::Bubble.new(context: context, **options, &)
           end
 
           def to_h
-            raise RequiredError, "contents should have at least 1 bubble" if @contents.empty?
-            raise ValidationError, "contents should have at most 12 bubbles" if @contents.size > 12
+            raise RequiredError, "Carousel contents must have at least 1 bubble." if @contents.empty?
+            # LINE API as of 2023-10-10 allows up to 12 bubbles in a carousel.
+            raise ValidationError, "Carousel contents can have at most 12 bubbles." if @contents.size > 12
+
+            return to_sdkv2 if context.sdkv2?
+
+            to_api
+          end
+
+          private
+
+          def to_api
+            {
+              type: "carousel",
+              contents: @contents.map(&:to_h) # Serializes each Bubble in the array
+            }.compact # compact is likely unnecessary here as contents is always present.
+          end
 
+          def to_sdkv2
             {
               type: "carousel",
-              contents: @contents.map(&:to_h)
-            }.compact
+              contents: @contents.map(&:to_h) # Serializes each Bubble in the array
+            }.compact # compact is likely unnecessary here as contents is always present.
           end
         end
       end

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

@@ -4,36 +4,93 @@ module Line
   module Message
     module Builder
       module Flex
-        # The image is a component for the Flex message.
+        # Represents an "image" component in a LINE Flex Message.
+        #
+        # Images are specified by a URL and can be included in various parts of a
+        # Flex Message, such as a box, a bubble's hero section, etc. They offer
+        # several properties to control their appearance, including `size`,
+        # `aspect_ratio`, and `aspect_mode`. An image can also have an
+        # {Actionable#action action} to make it tappable.
+        #
+        # @example Creating an image component within a box
+        #   Line::Message::Builder.with do |root|
+        #     root.flex alt_text: "Image Example" do |flex|
+        #       flex.bubble do |bubble|
+        #         bubble.body do |body_box|
+        #           body_box.image "https://example.com/image.png",
+        #                          aspect_ratio: "16:9",
+        #                          aspect_mode: :cover,
+        #                          size: :full do |img_action|
+        #             img_action.message "View Details", text: "Show details for image"
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # @see https://developers.line.biz/en/reference/messaging-api/#image
+        # @see Actionable For making the image 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::Image For `size` (image specific keywords), `aspect_ratio`, `aspect_mode`.
         class Image < Line::Message::Builder::Base
-          include Actionable
-          include Position::Horizontal
-          include Position::Vertical
-          include Position::Margin
-          include Position::Offset
-          include Size::Flex
-          include Size::Image
+          include Actionable           # Enables defining an action for the image.
+          include Position::Horizontal # Adds `align` option for horizontal alignment.
+          include Position::Vertical   # Adds `gravity` option for vertical alignment.
+          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::Image          # Adds image-specific sizing options like `size`, `aspect_ratio`, `aspect_mode`.
 
+          # @!attribute [r] url
+          #   @return [String] The URL of the image. Must be HTTPS.
+          #     This is a required attribute.
           attr_reader :url
 
+          # Specifies the aspect ratio of the image (width:height).
+          # E.g., "1:1", "16:9", "20:13". Default is "1:1".
+          # @!method aspect_ratio(value)
+          #   @param value [String, nil] The aspect ratio string.
+          #   @return [String, nil] The current aspect ratio.
           option :aspect_ratio, default: nil
-          option :aspect_mode, default: nil
 
+          # Specifies how the image should be displayed within the area defined by `aspect_ratio`.
+          # @!method aspect_mode(value)
+          #   @param value [Symbol, String, nil] Aspect mode. Can be `:cover` (default)
+          #     or `:fit`.
+          #   @return [Symbol, String, nil] The current aspect mode.
+          option :aspect_mode, default: nil # :cover, :fit
+
+          # Initializes a new Flex Message Image component.
+          #
+          # @param url [String] The HTTPS URL of the image. 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., `:aspect_ratio`, `:aspect_mode`, `:size`, and options from included modules).
+          # @param block [Proc, nil] An optional block, typically used to define an
+          #   {Actionable#action action} for the image.
+          # @raise [ArgumentError] if `url` is nil (though the more specific `RequiredError`
+          #   is raised in `to_h`).
           def initialize(url, context: nil, **options, &)
-            @url = url
+            @url = url # The image URL is mandatory.
 
-            super(context: context, **options, &)
+            super(context: context, **options, &) # Sets options and evals block (for action).
           end
 
-          def to_h # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
-            raise RequiredError, "url is required" if url.nil?
+          private
+
+          def to_api # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            raise RequiredError, "url is required for an image component" if url.nil?
 
             {
               type: "image",
               url: url,
-              # Position
-              align: align,
-              gravity: gravity,
+              # Position::Horizontal & Position::Vertical
+              align: align,     # From Position::Horizontal
+              gravity: gravity, # From Position::Vertical
               # Position::Margin
               margin: margin,
               # Position::Offset
@@ -44,11 +101,40 @@ module Line
               offsetEnd: offset_end,
               # Size::Flex
               flex: flex,
-              # Size::Image
+              # Size::Image (includes aspect_ratio, aspect_mode, and specific image size keywords)
+              size: size,
+              aspectRatio: aspect_ratio, # From option
+              aspectMode: aspect_mode,   # From option
+              # Actionable
+              action: action&.to_h # From Actionable module
+            }.compact
+          end
+
+          def to_sdkv2 # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+            raise RequiredError, "url is required for an image component" if url.nil?
+
+            {
+              type: "image",
+              url: url,
+              # 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::Image (includes aspect_ratio, aspect_mode, and specific image size keywords)
               size: size,
-              aspectRatio: aspect_ratio,
-              aspectMode: aspect_mode,
-              action: action&.to_h
+              aspect_ratio: aspect_ratio, # From option
+              aspect_mode: aspect_mode,   # From option
+              # Actionable
+              action: action&.to_h # From Actionable module
             }.compact
           end
         end

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

@@ -4,32 +4,112 @@ module Line
   module Message
     module Builder
       module Flex
-        # Define a partial that can be reused in flex message.
+        # The `HasPartial` module provides functionality for Flex Message components
+        # (like {Box}, {Bubble}) to render reusable "partials". Partials are defined
+        # by creating classes that inherit from {Partial}.
+        #
+        # Including this module into a component class gives it the {#partial!} method.
+        #
+        # @example Defining and using a partial
+        #   # Define a reusable partial
+        #   class MyButtonPartial < Line::Message::Builder::Flex::Partial
+        #     def call(label:, data:)
+        #       # `button` method is available from the context (e.g., a Box)
+        #       button style: :primary do |btn|
+        #         btn.postback data, label: label
+        #       end
+        #     end
+        #   end
+        #
+        #   # Use the partial within a Box component
+        #   a_box_component.instance_eval do
+        #     # ... other box content ...
+        #     partial! MyButtonPartial, label: "Action", data: "action=do_something"
+        #     # ... other box content ...
+        #   end
+        #
+        # @see Partial
         module HasPartial
-          def partial!(partial, **assigns)
-            raise ArgumentError, "Not a partial" unless partial < Partial
+          # Renders a given {Partial} class within the current component's context.
+          #
+          # This method temporarily makes the provided `assigns` available to the
+          # partial through the `context.assigns` mechanism. After the partial's
+          # `call` method completes, the original `context.assigns` are restored.
+          #
+          # @param partial_class [Class] The class of the partial to render. Must be a
+          #   subclass of {Partial}.
+          # @param assigns [Hash] A hash of key-value pairs that will be made
+          #   available as `assigns` within the partial's `call` method.
+          # @return [void]
+          # @raise [ArgumentError] if `partial_class` is not a subclass of {Partial}.
+          def partial!(partial_class, **assigns)
+            unless partial_class < Partial
+              raise ArgumentError,
+                    "Argument must be a Line::Message::Builder::Flex::Partial class"
+            end
 
-            prev = context.assigns
+            original_assigns = context.assigns
             context.assigns = assigns
-            partial.new(context: self).call
-            context.assigns = prev
+            # `self` here is the component instance (e.g., Box, Bubble) that includes HasPartial.
+            # This component instance becomes the `@context` for the Partial instance.
+            partial_class.new(context: self).call
+            context.assigns = original_assigns
           end
         end
 
-        # The partial designed to be reused in flex message.
+        # The `Partial` class is an abstract base for creating reusable snippets
+        # of Flex Message content. To define a partial, create a new class that
+        # inherits from `Partial` and implements the {#call} instance method.
+        #
+        # Within the `call` method, you can use the standard Flex Message builder
+        # DSL methods (e.g., `text`, `box`, `button`) as if you were directly inside
+        # the component where the partial is being rendered. This is possible because
+        # the `Partial` instance delegates unknown method calls to the component
+        # instance that is rendering it (passed as `context` during initialization).
+        #
+        # @abstract Subclass and implement {#call} to create a concrete partial.
+        # @see HasPartial For how to render partials.
         class Partial
+          # Initializes a new Partial instance.
+          # This is typically called by the {HasPartial#partial!} method.
+          #
+          # @param context [Object] The component instance (e.g., {Box}, {Bubble})
+          #   within which this partial is being rendered. This context provides
+          #   the DSL methods (like `text`, `box`) used in the partial's `call` method.
           def initialize(context:)
-            @context = context
+            @context = context # The component (e.g., Box, Bubble) rendering this partial
           end
 
+          # This method must be implemented by subclasses to define the content of
+          # the partial. Inside this method, use the Flex Message builder DSL methods
+          # (e.g., `text "Hello"`, `button { ... }`) which will be delegated to the
+          # rendering context.
+          #
+          # Any arguments passed to `partial!` as `assigns` are available via
+          # `context.assigns` or directly if the rendering context's `method_missing`
+          # handles `assigns` lookup (as {Line::Message::Builder::Context} does).
+          #
+          # @param ... [Object] Arguments passed from the `partial!` call's `assigns`
+          #   can be explicitly defined as parameters here, or accessed via `context.assigns`.
+          # @raise [NotImplementedError] if a subclass does not implement this method.
           def call(*)
-            raise NotImplementedError, "The #{self.class} class must implement the call method"
+            raise NotImplementedError,
+                  "The #{self.class.name} class must implement the #call method to define its content."
           end
 
+          # @!visibility private
+          # Part of Ruby's dynamic method dispatch. It's overridden here to declare
+          # that instances of `Partial` can respond to methods to which the
+          # wrapped `@context` object responds.
           def respond_to_missing?(method_name, include_private = false)
             @context.respond_to?(method_name, include_private) || super
           end
 
+          # @!visibility private
+          # Handles calls to methods not explicitly defined on the `Partial` class
+          # by delegating them to the wrapped `@context` object (the rendering component).
+          # This allows the `call` method of a partial to use DSL methods like `text`,
+          # `box`, `button`, etc., as if they were defined directly in the partial.
           def method_missing(method_name, ...)
             if @context.respond_to?(method_name)
               @context.public_send(method_name, ...)