line-message-builder 0.9.0 → 0.10.0

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

@@ -4,34 +4,39 @@ module Line
   module Message
     module Builder
       module Flex
-        # The `Position` module serves as a namespace for several mixin modules
+        # 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}).
+        # 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.
+        # See also:
+        # - Horizontal for +align+ property
+        # - Vertical for +gravity+ property
+        # - Padding for +padding_all+, +padding_top+, etc. properties
+        # - Margin for +margin+ property
+        # - Offset for +position+, +offset_top+, etc. properties
         module Position
-          # 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
+          # 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
+            ##
+            # :method: align
+            # :call-seq:
+            #   align() -> Symbol, String, or nil
+            #   align(value) -> Symbol, String, or nil
+            #
+            # Sets or gets the horizontal alignment.
+            #
+            # [value]
+            #   Alignment keyword: +:start+ (aligns to the start of the horizontal space),
+            #   +:center+ (aligns to the center), +:end+ (aligns to the end)
+
+            # :nodoc:
             def self.included(base)
               base.option :align,
                           default: nil,
@@ -41,20 +46,24 @@ module Line
             end
           end
 
-          # 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
+          # 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
+            ##
+            # :method: gravity
+            # :call-seq:
+            #   gravity() -> Symbol, String, or nil
+            #   gravity(value) -> Symbol, String, or nil
+            #
+            # Sets or gets the vertical alignment (gravity).
+            #
+            # [value]
+            #   Gravity keyword: +:top+ (aligns to the top), +:center+ (aligns to the center),
+            #   +:bottom+ (aligns to the bottom)
+
+            # :nodoc:
             def self.included(base)
               base.option :gravity, # NOTE: API key is `gravity` (lowercase `g`)
                           default: nil,
@@ -67,40 +76,83 @@ module Line
           # 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`.
+          # Note: In this DSL, +padding+ is an alias for +padding_all+.
+          # The LINE API uses +paddingAll+. When using the DSL <code>padding(value)</code>,
+          # it sets the underlying value that will be output as +paddingAll+.
           module Padding
-            # @!visibility private
+            ##
+            # :method: padding
+            # :call-seq:
+            #   padding() -> String, Symbol, or nil
+            #   padding(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the padding for all sides (alias for +padding_all+).
+            # Corresponds to LINE API +paddingAll+.
+            #
+            # [value]
+            #   Padding value (e.g. <code>"10px"</code>, <code>"md"</code>, <code>"5%"</code>).
+            #   Keywords: +:none+, +:xs+, +:sm+, +:md+, +:lg+, +:xl+, +:xxl+
+
+            ##
+            # :method: padding_all
+            # :call-seq:
+            #   padding_all() -> String, Symbol, or nil
+            #   padding_all(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the padding for all sides.
+            # Corresponds to LINE API +paddingAll+.
+            #
+            # [value]
+            #   Padding value (e.g. <code>"10px"</code>, <code>"md"</code>, <code>"5%"</code>).
+            #   Keywords: +:none+, +:xs+, +:sm+, +:md+, +:lg+, +:xl+, +:xxl+
+
+            ##
+            # :method: padding_top
+            # :call-seq:
+            #   padding_top() -> String, Symbol, or nil
+            #   padding_top(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the top padding. Corresponds to LINE API +paddingTop+.
+            #
+            # [value]
+            #   Padding value
+
+            ##
+            # :method: padding_bottom
+            # :call-seq:
+            #   padding_bottom() -> String, Symbol, or nil
+            #   padding_bottom(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the bottom padding. Corresponds to LINE API +paddingBottom+.
+            #
+            # [value]
+            #   Padding value
+
+            ##
+            # :method: padding_start
+            # :call-seq:
+            #   padding_start() -> String, Symbol, or nil
+            #   padding_start(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the start-edge padding (left in LTR, right in RTL).
+            # Corresponds to LINE API +paddingStart+.
+            #
+            # [value]
+            #   Padding value
+
+            ##
+            # :method: padding_end
+            # :call-seq:
+            #   padding_end() -> String, Symbol, or nil
+            #   padding_end(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the end-edge padding (right in LTR, left in RTL).
+            # Corresponds to LINE API +paddingEnd+.
+            #
+            # [value]
+            #   Padding value
+
+            # :nodoc:
             def self.included(base)
               # Individual side paddings
               %i[padding padding_all padding_top padding_bottom padding_start padding_end].each do |option_name|
@@ -111,16 +163,22 @@ module Line
             end
           end
 
-          # Provides the `margin` option, allowing space to be defined around a
+          # 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
+            ##
+            # :method: margin
+            # :call-seq:
+            #   margin() -> String, Symbol, or nil
+            #   margin(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the margin space around the component.
+            #
+            # [value]
+            #   Margin value (e.g. <code>"10px"</code>, <code>"md"</code>).
+            #   Keywords: +:none+, +:xs+, +:sm+, +:md+, +:lg+, +:xl+, +:xxl+
+
+            # :nodoc:
             def self.included(base)
               base.option :margin,
                           default: nil,
@@ -130,35 +188,64 @@ module Line
 
           # 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
+            ##
+            # :method: position
+            # :call-seq:
+            #   position() -> Symbol, String, or nil
+            #   position(value) -> Symbol, String, or nil
+            #
+            # Sets or gets the positioning scheme.
+            #
+            # [value]
+            #   Positioning type: +:relative+ (default, offsets are relative to normal position),
+            #   +:absolute+ (offsets are relative to the parent component's edges)
+
+            ##
+            # :method: offset_top
+            # :call-seq:
+            #   offset_top() -> String, Symbol, or nil
+            #   offset_top(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the top offset. Corresponds to LINE API +offsetTop+.
+            #
+            # [value]
+            #   Offset value (e.g. <code>"10px"</code>, <code>"md"</code>)
+
+            ##
+            # :method: offset_bottom
+            # :call-seq:
+            #   offset_bottom() -> String, Symbol, or nil
+            #   offset_bottom(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the bottom offset. Corresponds to LINE API +offsetBottom+.
+            #
+            # [value]
+            #   Offset value
+
+            ##
+            # :method: offset_start
+            # :call-seq:
+            #   offset_start() -> String, Symbol, or nil
+            #   offset_start(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the start-edge offset. Corresponds to LINE API +offsetStart+.
+            #
+            # [value]
+            #   Offset value
+
+            ##
+            # :method: offset_end
+            # :call-seq:
+            #   offset_end() -> String, Symbol, or nil
+            #   offset_end(value) -> String, Symbol, or nil
+            #
+            # Sets or gets the end-edge offset. Corresponds to LINE API +offsetEnd+.
+            #
+            # [value]
+            #   Offset value
+
+            # :nodoc:
             def self.included(base)
               base.option :position,
                           default: nil, # LINE API default is :relative if offsets are used

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

@@ -4,13 +4,14 @@ module Line
   module Message
     module Builder
       module Flex
-        # Represents a "separator" component in a LINE Flex Message.
+        # Represents a separator component in a LINE Flex Message.
         #
         # Separator components are used to create a visual separation between components
         # within a container. They draw a horizontal line that helps organize the layout
         # and improve readability.
         #
-        # @example Creating a separator within a box
+        # == Example
+        #
         #   Line::Message::Builder.with do
         #     flex alt_text: "Separator Example" do
         #       bubble do
@@ -23,16 +24,58 @@ module Line
         #     end
         #   end
         #
-        # @see https://developers.line.biz/en/reference/messaging-api/#separator
+        # === Example: Spacing and tinting the line
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Separator Example" do
+        #       bubble do
+        #         body do
+        #           text "Section 1"
+        #           separator margin: :xl, color: "#F0F0F0"
+        #           text "Section 2"
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#separator
+        # - Position::Margin for the +margin+ property
         class Separator < Line::Message::Builder::Base
+          include Position::Margin # Adds `margin` option.
+
+          # :method: color
+          # :call-seq:
+          #   color() -> String or nil
+          #   color(value) -> String
+          #
+          # Sets or gets the color of the separator line.
+          #
+          # [value]
+          #   Hexadecimal color code (e.g., <code>"#RRGGBB"</code>)
+          option :color, default: nil
+
           # Converts the separator component to a hash representation compatible with
           # the LINE Messaging API.
           #
-          # @return [Hash] A hash containing the separator component's type.
+          # The +margin+ and +color+ properties share the same name in both the API
+          # and SDK v2 formats, so a single representation serves both.
+          #
+          # Returns a hash containing the separator component's type and any set
+          # properties.
+          #
+          # == Example
+          #
+          #   separator = Separator.new(margin: :md)
+          #   separator.to_h
+          #   # => { type: "separator", margin: :md }
           def to_h
             {
-              type: "separator"
-            }
+              type: "separator",
+              # Position::Margin
+              margin: margin,
+              color: color # From option
+            }.compact
           end
         end
       end

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

@@ -4,50 +4,61 @@ module Line
   module Message
     module Builder
       module Flex
-        # The `Size` module acts as a namespace for several mixin modules that
+        # 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})
+        # 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).
+        # See also:
+        # - Flex - For +flex+ property (flex grow/shrink factor)
+        # - Image - For image-specific +size+ keywords
+        # - Shared - For common +size+ keywords (text, icons, spans)
+        # - AdjustMode - For +adjust_mode+ property (e.g., shrink-to-fit)
         module Size
-          # Provides the `flex` option, which determines the ratio of space a
-          # component occupies within its parent {Box} relative to its siblings.
+          # 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
+            ##
+            # :method: flex
+            # :call-seq:
+            #   flex() -> Integer or nil
+            #   flex(value) -> Integer
+            #
+            # Sets or gets the flex factor of the component.
+            #
+            # [value]
+            #   The flex factor. +0+ means no flex. Positive integers determine the ratio.
+
+            # :nodoc:
             def self.included(base)
               base.option :flex,
                           default: nil # Default is 0 if not specified and parent is a Box
             end
           end
 
-          # Provides the `size` option specifically for {Image} components.
+          # 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
+            ##
+            # :method: size
+            # :call-seq:
+            #   size() -> Symbol, String, or nil
+            #   size(value) -> Symbol or String
+            #
+            # Sets or gets the size of the image.
+            #
+            # [value]
+            #   Image size. Can be keywords like +:xxs+, +:xs+, +:sm+, +:md+, +:lg+,
+            #   +:xl+, +:xxl+, +:full+, or a string like <code>"50px"</code> or <code>"25%"</code>.
+
+            # :nodoc:
             def self.included(base)
               base.option :size,
                           default: nil,
@@ -55,18 +66,23 @@ module Line
             end
           end
 
-          # Provides a common `size` option for components like {Text}, {Icon},
-          # and {Span}. This allows setting size using standard keywords or explicit
+          # 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
+            ##
+            # :method: size
+            # :call-seq:
+            #   size() -> Symbol, String, or nil
+            #   size(value) -> Symbol or String
+            #
+            # Sets or gets the size of the component (e.g., text font size).
+            #
+            # [value]
+            #   Component size. Can be keywords like +:xxs+, +:xs+, +:sm+, +:md+, +:lg+,
+            #   +:xl+, +:xxl+, +:3xl+, +:4xl+, +:5xl+, or a string like <code>"16px"</code>.
+
+            # :nodoc:
             def self.included(base)
               base.option :size,
                           default: nil,
@@ -74,17 +90,22 @@ module Line
             end
           end
 
-          # Provides the `adjust_mode` option, primarily for {Button} 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.
+          # <code>:"shrink-to-fit"</code> is supported by LINE API via this property.
           module AdjustMode
-            # @!visibility private
+            ##
+            # :method: adjust_mode
+            # :call-seq:
+            #   adjust_mode() -> Symbol, String, or nil
+            #   adjust_mode(value) -> Symbol or String
+            #
+            # Sets or gets the adjust mode.
+            #
+            # [value]
+            #   The adjust mode. Currently, only <code>:"shrink-to-fit"</code> is a valid value.
+
+            # :nodoc:
             def self.included(base)
               base.option :adjust_mode,
                           default: nil,
@@ -93,12 +114,11 @@ module Line
                           )
             end
 
-            # A convenience DSL method to set the `adjust_mode` to `:"shrink-to-fit"`.
+            # A convenience DSL method to set the +adjust_mode+ to <code>:"shrink-to-fit"</code>.
             #
-            # @example
-            #   button_component.shrink_to_fit!
+            # == Example
             #
-            # @return [Symbol] The value `:"shrink-to-fit"`.
+            #   button_component.shrink_to_fit!
             def shrink_to_fit!
               adjust_mode(:"shrink-to-fit")
             end