line-message-builder 0.9.0 → 0.10.0

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Line
+  module Message
+    module Builder
+      module Flex
+        # Represents an "icon" component in a LINE Flex Message.
+        #
+        # Icons render a small image that decorates the text next to them. They are
+        # the standard way to build rating stars, labelled metadata rows, and other
+        # icon-and-text pairs.
+        #
+        # An icon can only be placed in a box whose +layout+ is +:baseline+. Unlike
+        # Image, an icon cannot have an action attached to it.
+        #
+        # == Example: Rating stars beside a score
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Review" do
+        #       bubble do
+        #         body do
+        #           box layout: :baseline do
+        #             icon "https://example.com/star_on.png", size: :sm
+        #             icon "https://example.com/star_on.png", size: :sm
+        #             icon "https://example.com/star_off.png", size: :sm
+        #             text "3.0", size: :sm, margin: :md
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # === Example: Following the reader's font size
+        #
+        #   box layout: :baseline do
+        #     icon "https://example.com/pin.png", scaling: true
+        #     text "Taipei", scaling: true
+        #   end
+        #
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#icon
+        # - Position::Margin for +margin+ property
+        # - Position::Offset for offset properties
+        # - Size::Shared for common +size+ keywords (e.g., +:sm+, +:xl+)
+        class Icon < Line::Message::Builder::Base
+          include Position::Margin # Adds `margin` option.
+          include Position::Offset # Adds offset options.
+          include Size::Shared     # Adds `size` option (e.g., :sm, :md, :xl).
+
+          # The URL of the icon image (must be HTTPS). This is a required attribute.
+          attr_reader :url
+
+          # :method: aspect_ratio
+          # :call-seq:
+          #   aspect_ratio() -> String or nil
+          #   aspect_ratio(value) -> String
+          #
+          # Sets or gets the aspect ratio of the icon (width:height).
+          #
+          # [value]
+          #   The aspect ratio string (e.g., <code>"1:1"</code>, <code>"2:1"</code>).
+          #   Default is <code>"1:1"</code>
+          option :aspect_ratio, default: nil # API key: aspectRatio
+
+          # :method: scaling
+          # :call-seq:
+          #   scaling() -> Boolean or nil
+          #   scaling(value) -> Boolean
+          #
+          # Sets or gets whether the icon size follows the font size setting of the
+          # LINE app.
+          #
+          # [value]
+          #   +true+ to scale the icon, +false+ (default) to keep it fixed
+          option :scaling, default: nil
+
+          # Initializes a new Flex Message Icon component.
+          #
+          # [url]
+          #   The HTTPS URL of the icon image (required)
+          # [context]
+          #   An optional context for the builder (default: +nil+)
+          # [options]
+          #   A hash of options to set instance variables (e.g., +:size+,
+          #   +:aspect_ratio+, and options from included modules)
+          # [block]
+          #   An optional block for further configuration
+          #
+          # Raises RequiredError if +url+ is +nil+ when building the message.
+          #
+          # == Example
+          #
+          #   Line::Message::Builder::Flex::Icon.new(
+          #     "https://example.com/star.png",
+          #     size: :sm
+          #   )
+          def initialize(url, context: nil, **options, &)
+            @url = url # The icon URL is mandatory.
+
+            super(context: context, **options, &)
+          end
+
+          private
+
+          # :nodoc:
+          def to_api # rubocop:disable Metrics/MethodLength
+            raise RequiredError, "url is required for an icon component" if url.nil?
+
+            {
+              type: "icon",
+              url: url,
+              # Position::Margin
+              margin: margin,
+              # Position::Offset
+              position: position,
+              offsetTop: offset_top,
+              offsetBottom: offset_bottom,
+              offsetStart: offset_start,
+              offsetEnd: offset_end,
+              # Size::Shared
+              size: size,
+              aspectRatio: aspect_ratio, # From option (maps to API key)
+              scaling: scaling # From option
+            }.compact
+          end
+
+          # :nodoc:
+          def to_sdkv2 # rubocop:disable Metrics/MethodLength
+            raise RequiredError, "url is required for an icon component" if url.nil?
+
+            {
+              type: "icon",
+              url: url,
+              # 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::Shared
+              size: size,
+              aspect_ratio: aspect_ratio, # From option (maps to API key)
+              scaling: scaling # From option
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,11 +8,12 @@ module Line
         #
         # 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.
+        # several properties to control their appearance, including +size+,
+        # +aspect_ratio+, +aspect_mode+ and +background_color+. An image can also
+        # have an action to make it tappable.
+        #
+        # == Example
         #
-        # @example Creating an image component within a box
         #   Line::Message::Builder.with do
         #     flex alt_text: "Image Example" do
         #       bubble do
@@ -27,14 +28,27 @@ module Line
         #     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`.
+        # === Example: Playing an animated image on a tinted backdrop
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Image Example" do
+        #       bubble do
+        #         hero_image "https://example.com/loading.png",
+        #                    animated: true,
+        #                    background_color: "#FFFFFF"
+        #       end
+        #     end
+        #   end
+        #
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#image
+        # - Actionable for making the image tappable
+        # - Position::Horizontal for +align+ property
+        # - Position::Vertical for +gravity+ property
+        # - Position::Margin for +margin+ property
+        # - Position::Offset for offset properties
+        # - Size::Flex for +flex+ sizing property
+        # - Size::Image for +size+, +aspect_ratio+, and +aspect_mode+ properties
         class Image < Line::Message::Builder::Base
           include Actionable           # Enables defining an action for the image.
           include Position::Horizontal # Adds `align` option for horizontal alignment.
@@ -44,35 +58,77 @@ module Line
           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.
+          # 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.
+          # :method: aspect_ratio
+          # :call-seq:
+          #   aspect_ratio() -> String or nil
+          #   aspect_ratio(value) -> String
+          #
+          # Sets or gets the aspect ratio of the image (width:height).
+          #
+          # [value]
+          #   The aspect ratio string (e.g., <code>"1:1"</code>, <code>"16:9"</code>,
+          #   <code>"20:13"</code>). Default is <code>"1:1"</code>.
           option :aspect_ratio, 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.
+          # :method: aspect_mode
+          # :call-seq:
+          #   aspect_mode() -> Symbol or nil
+          #   aspect_mode(value) -> Symbol
+          #
+          # Sets or gets how the image should be displayed within the area defined by +aspect_ratio+.
+          #
+          # [value]
+          #   The aspect mode (can be +:cover+ (default) or +:fit+)
           option :aspect_mode, default: nil # :cover, :fit
 
+          # :method: background_color
+          # :call-seq:
+          #   background_color() -> String or nil
+          #   background_color(value) -> String
+          #
+          # Sets or gets the background color shown behind the image.
+          #
+          # [value]
+          #   Hexadecimal color code (e.g., <code>"#RRGGBB"</code>)
+          option :background_color, default: nil # API key: backgroundColor
+
+          # :method: animated
+          # :call-seq:
+          #   animated() -> Boolean or nil
+          #   animated(value) -> Boolean
+          #
+          # Sets or gets whether an animated image (APNG) is played back. A single
+          # message may mark at most 10 images as animated, and frames larger than
+          # 300 KB are not played.
+          #
+          # [value]
+          #   +true+ to play the animation, +false+ (default) to show a still frame
+          option :animated, default: nil
+
           # 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`).
+          # [url]
+          #   The HTTPS URL of the image (required)
+          # [context]
+          #   An optional context for the builder (default: +nil+)
+          # [options]
+          #   A hash of options to set instance variables (e.g., +:aspect_ratio+,
+          #   +:aspect_mode+, +:size+, and options from included modules)
+          # [block]
+          #   An optional block, typically used to define an action for the image
+          #
+          # Raises RequiredError if +url+ is +nil+ when building the message.
+          #
+          # == Example
+          #
+          #   image = Line::Message::Builder::Flex::Image.new(
+          #     "https://example.com/image.png",
+          #     aspect_ratio: "16:9",
+          #     aspect_mode: :cover
+          #   )
           def initialize(url, context: nil, **options, &)
             @url = url # The image URL is mandatory.
 
@@ -81,6 +137,7 @@ module Line
 
           private
 
+          # :nodoc:
           def to_api # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             raise RequiredError, "url is required for an image component" if url.nil?
 
@@ -104,11 +161,14 @@ module Line
               size: size,
               aspectRatio: aspect_ratio, # From option
               aspectMode: aspect_mode,   # From option
+              backgroundColor: background_color, # From option (maps to API key)
+              animated: animated, # From option
               # Actionable
               action: action&.to_h # From Actionable module
             }.compact
           end
 
+          # :nodoc:
           def to_sdkv2 # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             raise RequiredError, "url is required for an image component" if url.nil?
 
@@ -132,6 +192,8 @@ module Line
               size: size,
               aspect_ratio: aspect_ratio, # From option
               aspect_mode: aspect_mode,   # From option
+              background_color: background_color, # From option (maps to API key)
+              animated: animated, # From option
               # Actionable
               action: action&.to_h # From Actionable module
             }.compact

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

@@ -4,19 +4,20 @@ module Line
   module Message
     module Builder
       module Flex
-        # 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}.
+        # 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.
+        # Including this module into a component class gives it the +partial!+ method.
+        #
+        # == Example
         #
-        # @example Defining and using a partial
         #   # Define a reusable partial
         #   class MyButtonPartial < Line::Message::Builder::Flex::Partial
         #     def call
-        #       # `button` method is available from the context (e.g., a Box)
+        #       # +button+ method is available from the context (e.g., a Box)
         #       button style: :primary do
-        #         # `data` and `label` are available from `context.assigns`
+        #         # +data+ and +label+ are available from <code>context.assigns</code>
         #         postback data, label: label
         #       end
         #     end
@@ -33,20 +34,22 @@ module Line
         #     end
         #   end
         #
-        # @see Partial
+        # See also:
+        # - Partial
         module HasPartial
-          # Renders a given {Partial} class within the current component's context.
+          # Renders a given Partial class within the current component's context.
+          #
+          # This method temporarily makes the provided +assigns+ available to the
+          # partial through the <code>context.assigns</code> mechanism. After the partial's
+          # +call+ method completes, the original <code>context.assigns</code> are restored.
           #
-          # 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.
+          # [partial_class]
+          #   The class of the partial to render. Must be a subclass of Partial.
+          # [assigns]
+          #   A hash of key-value pairs that will be made available as +assigns+
+          #   within the partial's +call+ method.
           #
-          # @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}.
+          # Raises ArgumentError if +partial_class+ is not a subclass of Partial.
           def partial!(partial_class, **assigns)
             unless partial_class < Partial
               raise ArgumentError,
@@ -62,60 +65,55 @@ module Line
           end
         end
 
-        # The `Partial` class is an abstract base for creating reusable snippets
+        # 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.
+        # 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
+        # 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).
+        # 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.
+        # Subclass and implement +call+ to create a concrete partial.
+        #
+        # See also:
+        # - HasPartial for how to render partials
         class Partial
           # Initializes a new Partial instance.
-          # This is typically called by the {HasPartial#partial!} method.
+          # 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.
+          # [context]
+          #   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 # 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.
+          # (e.g., <code>text "Hello"</code>, <code>button { ... }</code>) which will be
+          # delegated to the rendering context.
+          #
+          # Any arguments passed to +partial!+ as +assigns+ are available via
+          # <code>context.assigns</code> or directly if the rendering context's +method_missing+
+          # handles +assigns+ lookup (as Line::Message::Builder::Context does).
           #
-          # 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).
+          # Arguments passed from the +partial!+ call's +assigns+ can be explicitly defined
+          # as parameters here, or accessed via <code>context.assigns</code>.
           #
-          # @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.
+          # Raises NotImplementedError if a subclass does not implement this method.
           def call(*)
             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)
+          def respond_to_missing?(method_name, include_private = false) # :nodoc:
             @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, ...)
+          def method_missing(method_name, ...) # :nodoc:
             if @context.respond_to?(method_name)
               @context.public_send(method_name, ...)
             else