line-message-builder 0.7.0 → 0.8.0

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

@@ -4,9 +4,34 @@ module Line
   module Message
     module Builder
       module Flex
+        # The `Position` module serves as a namespace for several mixin modules
+        # that provide common positioning-related properties (options) to various
+        # Flex Message components (like {Box}, {Text}, {Image}, {Button}).
+        #
+        # These mixins are included in component classes to add DSL methods for
+        # setting properties like alignment, gravity, padding, margin, and offsets,
+        # which correspond to attributes in the LINE Flex Message JSON structure.
+        #
+        # @see Horizontal For `align` property.
+        # @see Vertical For `gravity` property.
+        # @see Padding For `paddingAll`, `paddingTop`, etc. properties.
+        # @see Margin For `margin` property.
+        # @see Offset For `position`, `offsetTop`, etc. properties.
         module Position
-          # The horizontal provides "align" options for flex components.
+          # Provides the `align` option for horizontal alignment of a component
+          # within its parent {Box} (if the parent box's `layout` is vertical).
+          # For components like {Image} or {Text}, this controls their horizontal
+          # alignment within the space allocated to them.
+          #
+          # @!method align(value)
+          #   Sets or gets the horizontal alignment.
+          #   @param value [Symbol, String, nil] Alignment keyword:
+          #     `:start` (aligns to the start of the horizontal space),
+          #     `:center` (aligns to the center),
+          #     `:end` (aligns to the end).
+          #   @return [Symbol, String, nil] The current alignment value.
           module Horizontal
+            # @!visibility private
             def self.included(base)
               base.option :align,
                           default: nil,
@@ -16,10 +41,22 @@ module Line
             end
           end
 
-          # The vertical provides "gatvity" options for flex components.
+          # Provides the `gravity` option for vertical alignment of a component
+          # within its parent {Box} (if the parent box's `layout` is horizontal
+          # or baseline). For components like {Image} or {Text}, this controls
+          # their vertical alignment within the space allocated to them.
+          #
+          # @!method gravity(value)
+          #   Sets or gets the vertical alignment (gravity).
+          #   @param value [Symbol, String, nil] Gravity keyword:
+          #     `:top` (aligns to the top),
+          #     `:center` (aligns to the center),
+          #     `:bottom` (aligns to the bottom).
+          #   @return [Symbol, String, nil] The current gravity value.
           module Vertical
+            # @!visibility private
             def self.included(base)
-              base.option :gravity,
+              base.option :gravity, # NOTE: API key is `gravity` (lowercase `g`)
                           default: nil,
                           validator: Validators::Enum.new(
                             :top, :center, :bottom
@@ -27,35 +64,108 @@ module Line
             end
           end
 
-          # The padding provides "padding" options for flex components.
+          # Provides padding options for components, allowing space to be defined
+          # around the content of a component, inside its borders.
+          #
+          # @!method padding_all(value)
+          #   Sets or gets the padding for all sides.
+          #   Corresponds to LINE API `paddingAll`.
+          #   @param value [String, Symbol, nil] Padding value (e.g., `"10px"`, `"md"`, `"5%"`).
+          #     Keywords: `:none`, `:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:xxl`.
+          #   @return [String, Symbol, nil] The current padding value.
+          #
+          # @!method padding_top(value)
+          #   Sets or gets the top padding. Corresponds to LINE API `paddingTop`.
+          #   @param value [String, Symbol, nil] Padding value.
+          #   @return [String, Symbol, nil] The current top padding.
+          #
+          # @!method padding_bottom(value)
+          #   Sets or gets the bottom padding. Corresponds to LINE API `paddingBottom`.
+          #   @param value [String, Symbol, nil] Padding value.
+          #   @return [String, Symbol, nil] The current bottom padding.
+          #
+          # @!method padding_start(value)
+          #   Sets or gets the start-edge padding (left in LTR, right in RTL).
+          #   Corresponds to LINE API `paddingStart`.
+          #   @param value [String, Symbol, nil] Padding value.
+          #   @return [String, Symbol, nil] The current start padding.
+          #
+          # @!method padding_end(value)
+          #   Sets or gets the end-edge padding (right in LTR, left in RTL).
+          #   Corresponds to LINE API `paddingEnd`.
+          #   @param value [String, Symbol, nil] Padding value.
+          #   @return [String, Symbol, nil] The current end padding.
+          #
+          # @note In this DSL, `padding` is an alias for `padding_all`.
+          #   The LINE API uses `paddingAll`. When using the DSL `padding(value)`,
+          #   it sets the underlying value that will be output as `paddingAll`.
           module Padding
+            # @!visibility private
             def self.included(base)
-              %i[padding padding_top padding_bottom padding_start padding_end].each do |option|
-                base.option option,
+              # Individual side paddings
+              %i[padding padding_all padding_top padding_bottom padding_start padding_end].each do |option_name|
+                base.option option_name, # e.g., maps to `paddingTop` in JSON
                             default: nil,
                             validator: Validators::Size.new(:pixel, :keyword, :percentage)
               end
             end
           end
 
-          # The margin provides "margin" options for flex components.
+          # Provides the `margin` option, allowing space to be defined around a
+          # component, outside its borders.
+          #
+          # @!method margin(value)
+          #   Sets or gets the margin space around the component.
+          #   @param value [String, Symbol, nil] Margin value (e.g., `"10px"`, `"md"`).
+          #     Keywords: `:none`, `:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:xxl`.
+          #   @return [String, Symbol, nil] The current margin value.
           module Margin
+            # @!visibility private
             def self.included(base)
               base.option :margin,
                           default: nil,
-                          validator: Validators::Size.new(:pixel, :keyword)
+                          validator: Validators::Size.new(:pixel, :keyword) # Percentage not allowed for margin
             end
           end
 
-          # The offset provides "offset" options for flex components.
+          # Provides options for positioning components using offsets, either
+          # absolutely or relatively to their normal position.
+          #
+          # @!method position(value)
+          #   Sets or gets the positioning scheme.
+          #   @param value [Symbol, String, nil] Positioning type:
+          #     `:relative` (default, offsets are relative to normal position),
+          #     `:absolute` (offsets are relative to the parent component's edges).
+          #   @return [Symbol, String, nil] The current position type.
+          #
+          # @!method offset_top(value)
+          #   Sets or gets the top offset. Corresponds to LINE API `offsetTop`.
+          #   @param value [String, Symbol, nil] Offset value (e.g., `"10px"`, `"md"`).
+          #   @return [String, Symbol, nil] The current top offset.
+          #
+          # @!method offset_bottom(value)
+          #   Sets or gets the bottom offset. Corresponds to LINE API `offsetBottom`.
+          #   @param value [String, Symbol, nil] Offset value.
+          #   @return [String, Symbol, nil] The current bottom offset.
+          #
+          # @!method offset_start(value)
+          #   Sets or gets the start-edge offset. Corresponds to LINE API `offsetStart`.
+          #   @param value [String, Symbol, nil] Offset value.
+          #   @return [String, Symbol, nil] The current start offset.
+          #
+          # @!method offset_end(value)
+          #   Sets or gets the end-edge offset. Corresponds to LINE API `offsetEnd`.
+          #   @param value [String, Symbol, nil] Offset value.
+          #   @return [String, Symbol, nil] The current end offset.
           module Offset
+            # @!visibility private
             def self.included(base)
               base.option :position,
-                          default: nil,
+                          default: nil, # LINE API default is :relative if offsets are used
                           validator: Validators::Enum.new(:absolute, :relative)
 
-              %i[offset_top offset_bottom offset_start offset_end].each do |option|
-                base.option option,
+              %i[offset_top offset_bottom offset_start offset_end].each do |option_name|
+                base.option option_name, # e.g., maps to `offsetTop` in JSON
                             default: nil,
                             validator: Validators::Size.new(:pixel, :keyword)
               end

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

@@ -4,17 +4,50 @@ module Line
   module Message
     module Builder
       module Flex
+        # The `Size` module acts as a namespace for several mixin modules that
+        # provide various size-related properties (options) to Flex Message
+        # components. These properties control aspects like the component's flex
+        # factor within a box, specific size keywords for images or text, and
+        # adjustment behaviors like shrink-to-fit.
+        #
+        # These mixins are included in component classes (e.g., {Box}, {Image}, {Text})
+        # to add DSL methods for these sizing attributes.
+        #
+        # @see Flex For `flex` property (flex grow/shrink factor).
+        # @see Image For image-specific `size` keywords.
+        # @see Shared For common `size` keywords (text, icons, spans).
+        # @see AdjustMode For `adjustMode` property (e.g., shrink-to-fit).
         module Size
-          # The flex size provides "flex" options for flex components.
+          # Provides the `flex` option, which determines the ratio of space a
+          # component occupies within its parent {Box} relative to its siblings.
+          # A higher flex value means the component will take up more space.
+          # A value of 0 means the component does not flex (its size is fixed).
+          #
+          # @!method flex(value)
+          #   Sets or gets the flex factor of the component.
+          #   @param value [Integer, nil] The flex factor. `0` means no flex.
+          #     Positive integers determine the ratio.
+          #   @return [Integer, nil] The current flex factor.
           module Flex
+            # @!visibility private
             def self.included(base)
               base.option :flex,
-                          default: nil
+                          default: nil # Default is 0 if not specified and parent is a Box
             end
           end
 
-          # The image provides "size" options for flex image component.
+          # Provides the `size` option specifically for {Image} components.
+          # This allows setting the image size using keywords recognized by the
+          # LINE API for images, or explicit pixel/percentage values.
+          #
+          # @!method size(value)
+          #   Sets or gets the size of the image.
+          #   @param value [Symbol, String, nil] Image size. Can be keywords like
+          #     `:xxs`, `:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:xxl`, `:full`,
+          #     or a string like `"50px"`, `"25%"`.
+          #   @return [Symbol, String, nil] The current image size.
           module Image
+            # @!visibility private
             def self.included(base)
               base.option :size,
                           default: nil,
@@ -22,8 +55,18 @@ module Line
             end
           end
 
-          # The shared provides "size" options for flex components which is icon, text and span.
+          # Provides a common `size` option for components like {Text}, {Icon},
+          # and {Span}. This allows setting size using standard keywords or explicit
+          # pixel values.
+          #
+          # @!method size(value)
+          #   Sets or gets the size of the component (e.g., text font size).
+          #   @param value [Symbol, String, nil] Component size. Can be keywords like
+          #     `:xxs`, `:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:xxl`, `3xl`, `4xl`, `5xl`,
+          #     or a string like `"16px"`.
+          #   @return [Symbol, String, nil] The current component size.
           module Shared
+            # @!visibility private
             def self.included(base)
               base.option :size,
                           default: nil,
@@ -31,18 +74,33 @@ module Line
             end
           end
 
-          # The adjust mode provides "adjust mode" options for flex components.
+          # Provides the `adjust_mode` option, primarily for {Button} components,
+          # to control how they fit within available space. Currently, only
+          # `shrink-to-fit` is supported by LINE API via this property.
+          #
+          # @!method adjust_mode(value)
+          #   Sets or gets the adjust mode.
+          #   @param value [Symbol, String, nil] The adjust mode. Currently, only
+          #     `:"shrink-to-fit"` is a valid value.
+          #   @return [Symbol, String, nil] The current adjust mode.
           module AdjustMode
+            # @!visibility private
             def self.included(base)
               base.option :adjust_mode,
                           default: nil,
                           validator: Validators::Enum.new(
-                            :"shrink-to-fit"
+                            :"shrink-to-fit" # LINE API uses "shrink-to-fit"
                           )
             end
 
+            # A convenience DSL method to set the `adjust_mode` to `:"shrink-to-fit"`.
+            #
+            # @example
+            #   button_component.shrink_to_fit!
+            #
+            # @return [Symbol] The value `:"shrink-to-fit"`.
             def shrink_to_fit!
-              @adjust_mode = :"shrink-to-fit"
+              adjust_mode(:"shrink-to-fit")
             end
           end
         end

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

@@ -4,43 +4,121 @@ 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.
+        #
+        # @example Creating a text component within a box
+        #   Line::Message::Builder.with do |root|
+        #     root.flex alt_text: "Text Example" do |flex|
+        #       flex.bubble do |bubble|
+        #         bubble.body do |body_box|
+        #           body_box.text "Hello, Flex World!",
+        #                         size: :xl,
+        #                         color: "#FF0000",
+        #                         wrap: true do |txt_action|
+        #             txt_action.message "More info", text: "Tell me more about text"
+        #           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.
 
+          # @!attribute [r] text
+          #   @return [String] The actual text content to be displayed.
+          #     This is a required attribute.
           attr_reader :text
 
+          # 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, context: nil, **options, &)
+            @text = text_content # The text content is mandatory.
 
-            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
 
-          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" if text.nil?
+
+            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,
+              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 +129,39 @@ 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,
+              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,67 @@
 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 |root_container|
+      #     # This `flex` call on root_container would utilize Flex::Builder
+      #     root_container.flex(alt_text: "My Flex Message") do |flex_msg_builder|
+      #       flex_msg_builder.bubble do |bubble_builder|
+      #         # ... 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
       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.8.0"
     end
   end
 end