line-message-builder 0.6.1 → 0.8.0

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

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

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