line-message-builder 0.8.0 → 0.10.0

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

@@ -8,54 +8,73 @@ module Line
         # 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.
+        # 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!"
+        # == Example: Creating a simple bubble with a body
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Simple Bubble" do
+        #       bubble do
+        #         body do
+        #           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.
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#bubble
+        # - HasPartial
+        # - Box
+        # - Image
         class Bubble < Line::Message::Builder::Base
           include HasPartial # Allows including predefined partial component sets into sections.
 
+          # :method: size
+          #
+          # :call-seq:
+          #   size() -> Symbol, String, or nil
+          #   size(value) -> Symbol, String, or 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.
+          #
+          # [value]
+          #   Bubble size. Keywords: <code>:nano</code>, <code>:micro</code>,
+          #   <code>:kilo</code>, <code>:mega</code>, <code>:giga</code>.
+          #   Pixel/percentage values are not directly supported for bubble
+          #   size by LINE; use keywords.
           option :size, default: nil # E.g., :nano, :micro, :kilo, :mega, :giga
 
+          # :method: styles
+          #
+          # :call-seq:
+          #   styles() -> Hash or nil
+          #   styles(value) -> Hash or nil
+          #
           # 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" }
-          #     )
+          #
+          # [value]
+          #   A hash defining style overrides. See LINE API documentation
+          #   for the structure of the styles object.
+          #
+          # == 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.
+          # 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.
+          # [context]
+          #   An optional context for the builder.
+          # [option]
+          #   A hash of options to set instance variables (e.g., <code>:size</code>, <code>:styles</code>).
+          # [block]
+          #   A block to define the sections of this bubble.
           def initialize(context: nil, **options, &)
             @header = nil
             @hero = nil
@@ -65,57 +84,64 @@ module Line
             super # Calls Base#initialize, sets options, and evals block
           end
 
-          # Defines the header section of the bubble using a {Box} component.
+          # 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.
+          # [option]
+          #   Options for the header Box. See Box#initialize.
+          # [block]
+          #   A block to define the contents of the header Box.
           def header(**options, &)
             @header = Box.new(**options, context: context, &)
           end
 
-          # Defines the hero section of the bubble using a {Box} component.
+          # 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.
+          # [option]
+          #   Options for the hero Box. See Box#initialize.
+          # [block]
+          #   A block to define the contents of the hero Box.
           def hero(**options, &)
             @hero = Box.new(**options, context: context, &)
           end
 
-          # Defines the hero section of the bubble using an {Image} component.
+          # 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.
+          # [url]
+          #   The URL of the image.
+          # [option]
+          #   Options for the Image component. See Image#initialize.
+          # [block]
+          #   An optional block for the Image component (e.g., for an action).
           def hero_image(url, **options, &)
             @hero = Image.new(url, **options, context: context, &)
           end
 
-          # Defines the body section of the bubble using a {Box} component.
+          # 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.
+          # [option]
+          #   Options for the body Box. See Box#initialize.
+          # [block]
+          #   A block to define the contents of the body Box.
           def body(**options, &)
             @body = Box.new(**options, context: context, &)
           end
 
-          # Defines the footer section of the bubble using a {Box} component.
+          # 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.
+          # [option]
+          #   Options for the footer Box. See Box#initialize.
+          # [block]
+          #   A block to define the contents of the footer Box.
           def footer(**options, &)
             @footer = Box.new(**options, context: context, &)
           end
 
           private
 
+          # :nodoc:
           def to_api
             {
               type: "bubble",
@@ -128,6 +154,7 @@ module Line
             }.compact
           end
 
+          # :nodoc:
           def to_sdkv2
             {
               type: "bubble",

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

@@ -4,50 +4,59 @@ module Line
   module Message
     module Builder
       module Flex
-        # The `Builder` class is the main entry point for constructing a complete
+        # 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.
+        # Bubble or a Carousel of bubbles.
         #
-        # This builder requires `alt_text` (alternative text) for accessibility and
+        # 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.
+        # 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
+        # === Example: Creating a Flex Message with a single bubble
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "My Product" do
+        #       flex_builder.bubble size: :giga do
+        #         hero_image "https://example.com/product.jpg"
+        #         body do
+        #           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"
+        #       quick_reply do
+        #         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
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#flex-messages
+        # - Bubble
+        # - Carousel
+        # - 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.
+          #
+          # :method: alt_text
+          # :call-seq:
+          #   alt_text(value) -> String, nil
+          #
+          # [value]
+          #   The alternative text. Max 400 characters.
           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.
+          # #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)
+          # [context]
+          #   An optional context for the builder.
+          # [option]
+          #   A hash of options to set instance variables (e.g., <code>:alt_text</code>).
+          # [block]
+          #   A block to define the content (bubble or carousel)
           #   of this Flex Message.
           def initialize(context: nil, **options, &)
             @contents = nil # Will hold either a Bubble or Carousel instance
@@ -55,29 +64,31 @@ module Line
             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.
+          # 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.
+          # [option]
+          #   Options for the Bubble. See Bubble#initialize.
+          # [block]
+          #   A block to define the sections of the Bubble.
           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.
+          # 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.
+          # [option]
+          #   Options for the Carousel. See Carousel#initialize.
+          # [block]
+          #   A block to define the bubbles within the Carousel.
           def carousel(**options, &)
             @contents = Line::Message::Builder::Flex::Carousel.new(context: context, **options, &)
           end
 
           private
 
-          def to_api
+          def to_api # :nodoc:
             raise Error, "Flex Message contents (bubble or carousel) must be defined." if @contents.nil?
 
             {
@@ -88,7 +99,7 @@ module Line
             }.compact
           end
 
-          def to_sdkv2
+          def to_sdkv2 # :nodoc:
             raise Error, "Flex Message contents (bubble or carousel) must be defined." if @contents.nil?
 
             {

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

@@ -6,73 +6,128 @@ module Line
       module Flex
         # Represents a "button" component in a LINE Flex Message.
         #
-        # Buttons are interactive elements that users can tap to trigger an {Actionable#action action}
+        # Buttons are interactive elements that users can tap to trigger an 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`.
+        # various styling options, including +style+ (primary, secondary, link),
+        # +color+ 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
+        # Buttons have no padding properties of their own; use the padding of the
+        # surrounding Box to inset a button.
+        #
+        # == Example
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Button Example" do
+        #       bubble do
+        #         body do
+        #           button style: :primary, height: :sm do
+        #             message "Buy Now", label: "Buy" # Action definition
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # === Example: Tinting a primary button
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Button Example" do
+        #       bubble do
+        #         body do
+        #           button style: :primary, color: "#1DB446" do
+        #             message "Buy Now", label: "Buy"
         #           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.
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#button
+        # - Actionable for defining the button's action (mandatory)
+        # - Position::Vertical for +gravity+ property
+        # - Position::Margin for +margin+ property
+        # - Position::Offset for offset properties
+        # - Size::Flex for flex sizing property
+        # - Size::AdjustMode for +adjust_mode+ property
         class Button < Line::Message::Builder::Base
           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.
+          # :method: style
+          # :call-seq:
+          #   style() -> Symbol
+          #   style(value) -> Symbol
+          #
+          # Sets or gets the button style.
+          #
+          # [value]
+          #   Button style. Can be +:primary+, +:secondary+, or +:link+ (default).
+          #   String values should match these keywords.
           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.
+          # :method: height
+          # :call-seq:
+          #   height() -> Symbol
+          #   height(value) -> Symbol
+          #
+          # Sets or gets the button height.
+          #
+          # [value]
+          #   Button height. Can be +:sm+ (small) or +:md+ (medium, default).
           option :height, default: :md, validator: Validators::Enum.new(:sm, :md)
 
+          # :method: color
+          # :call-seq:
+          #   color() -> String or nil
+          #   color(value) -> String
+          #
+          # Sets or gets the button color. This is the character color when
+          # +style+ is <code>:link</code>, and the background color when +style+
+          # is <code>:primary</code> or <code>:secondary</code>.
+          #
+          # [value]
+          #   Hexadecimal color code (e.g., <code>"#RRGGBB"</code>)
+          option :color, default: nil
+
+          # :method: scaling
+          # :call-seq:
+          #   scaling() -> Boolean or nil
+          #   scaling(value) -> Boolean
+          #
+          # Sets or gets whether the label font size follows the font size setting
+          # of the LINE app.
+          #
+          # [value]
+          #   +true+ to scale the font size, +false+ (default) to keep it fixed
+          option :scaling, default: 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"`).
+          # button's action using methods from the Actionable module (e.g., +message+).
           #
-          # @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`.
+          # [context]
+          #   An optional context for the builder
+          # [options]
+          #   A hash of options to set instance variables
+          #   (e.g., +:style+, +:height+, and options from included modules)
+          # [block]
+          #   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
 
+          # :nodoc:
           def to_api # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             raise RequiredError, "action is required for a button" if action.nil?
 
@@ -81,14 +136,10 @@ module Line
               action: action.to_h, # From Actionable module
               style: style,         # From option
               height: height,       # From option
+              color: color,         # From option
+              scaling: scaling,     # From option
               # Position::Vertical
               gravity: gravity,
-              # Position::Padding
-              paddingAll: padding || padding_all,
-              paddingTop: padding_top,
-              paddingBottom: padding_bottom,
-              paddingStart: padding_start,
-              paddingEnd: padding_end,
               # Position::Margin
               margin: margin,
               # Position::Offset
@@ -104,6 +155,7 @@ module Line
             }.compact
           end
 
+          # :nodoc:
           def to_sdkv2 # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             raise RequiredError, "action is required for a button" if action.nil?
 
@@ -112,14 +164,10 @@ module Line
               action: action.to_h, # From Actionable module
               style: style,         # From option
               height: height,       # From option
+              color: color,         # From option
+              scaling: scaling,     # 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