line-message-builder 0.8.0 → 0.10.0

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Line
+  module Message
+    module Builder
+      module Flex
+        # Represents a span component in a LINE Flex Message.
+        #
+        # Span components are used within a Text component to apply different styling
+        # to specific portions of text. They offer various styling options, including
+        # +size+, +weight+, +color+, +style+ and +decoration+. Unlike Text
+        # components, spans cannot have actions attached to them.
+        #
+        # A +decoration+ set on the surrounding Text cannot be overridden by a span.
+        #
+        # == Example
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Span Example" do
+        #       bubble do
+        #         body do
+        #           text do
+        #             span "Hello, ", color: "#FF0000"
+        #             span "Flex ", weight: :bold
+        #             span "World!", size: :xl, decoration: :underline
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#span
+        # - Size::Shared for common size keywords (e.g., +:xl+, +:sm+)
+        class Span < Line::Message::Builder::Base
+          include Size::Shared # Adds `size` option (e.g., :sm, :md, :xl).
+
+          # The actual text content to be displayed. This is a required attribute.
+          attr_reader :text
+
+          # :method: color
+          # :call-seq:
+          #   color() -> String or nil
+          #   color(value) -> String
+          #
+          # Sets or gets the text color.
+          #
+          # [value]
+          #   Hexadecimal color code (e.g., <code>"#RRGGBB"</code>, <code>"#RRGGBBAA"</code>)
+          #
+          # == Example
+          #
+          #   span "Hello", color: "#FF0000"
+          option :color, default: nil
+
+          # :method: weight
+          # :call-seq:
+          #   weight() -> Symbol, String, or nil
+          #   weight(value) -> Symbol or String
+          #
+          # Sets or gets the text weight.
+          #
+          # [value]
+          #   Text weight. Valid values are +:regular+ and +:bold+
+          #
+          # == Example
+          #
+          #   span "Bold text", weight: :bold
+          option :weight, default: nil, validator: Validators::Enum.new(:regular, :bold)
+
+          # :method: decoration
+          # :call-seq:
+          #   decoration() -> Symbol, String, or nil
+          #   decoration(value) -> Symbol or String
+          #
+          # Sets or gets the text decoration.
+          #
+          # [value]
+          #   Text decoration. Valid values are +:none+, +:underline+, and <code>:line-through</code>
+          #
+          # == Example
+          #
+          #   span "Underlined", decoration: :underline
+          option :decoration, default: nil, validator: Validators::Enum.new(:none, :underline, :"line-through")
+
+          # :method: style
+          # :call-seq:
+          #   style() -> Symbol, String, or nil
+          #   style(value) -> Symbol or String
+          #
+          # Sets or gets the text style.
+          #
+          # [value]
+          #   Text style. Valid values are +:normal+ (default) and +:italic+
+          #
+          # == Example
+          #
+          #   span "Emphasised", style: :italic
+          option :style, default: nil, validator: Validators::Enum.new(:normal, :italic)
+
+          # Initializes a new Flex Message Span component.
+          #
+          # [text_content]
+          #   The text to display. This is required
+          # [context]
+          #   An optional context for the builder
+          # [options]
+          #   A hash of options to set instance variables (e.g., +:color+, +:weight+,
+          #   +:decoration+, and options from included modules)
+          # [block]
+          #   An optional block, typically not used for spans
+          #
+          # == Example
+          #
+          #   span "Hello", color: "#FF0000", weight: :bold
+          def initialize(text_content, context: nil, **options, &)
+            @text = text_content # The text content is mandatory.
+
+            super(context: context, **options, &) # Sets options and evals block
+          end
+
+          # Sets weight to bold.
+          #
+          # == Example
+          #
+          #   span "Bold text" do
+          #     bold!
+          #   end
+          def bold!
+            weight(:bold)
+          end
+
+          # Sets style to italic.
+          #
+          # == Example
+          #
+          #   span "Emphasised text" do
+          #     italic!
+          #   end
+          def italic!
+            style(:italic)
+          end
+
+          # Sets decoration to underline.
+          #
+          # == Example
+          #
+          #   span "Underlined text" do
+          #     underline!
+          #   end
+          def underline!
+            decoration(:underline)
+          end
+
+          # Sets decoration to line-through.
+          #
+          # == Example
+          #
+          #   span "Strikethrough text" do
+          #     line_through!
+          #   end
+          def line_through!
+            decoration(:"line-through")
+          end
+
+          # :nodoc:
+          def to_h
+            raise RequiredError, "text content is required for a span component" if text.nil?
+
+            {
+              type: "span",
+              text: text,
+              color: color,
+              size: size,
+              weight: weight,
+              style: style,
+              decoration: decoration
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,39 +4,74 @@ module Line
   module Message
     module Builder
       module Flex
-        # Represents a "text" component in a LINE 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.
+        # styling options, including font +size+, +weight+, +style+, +decoration+,
+        # +color+, +align+ment, +gravity+, text +wrap+ping, +line_spacing+,
+        # +max_lines+, +scaling+, and more. A text component can also have an
+        # 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"
+        # Text components also support embedded Span components, which allow parts of
+        # the text to have different styling. Spans can be added to a text component
+        # using the +span+ method within the Text component block.
+        #
+        # == Example: Creating a text component within a box
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Text Example" do
+        #       bubble do
+        #         body do
+        #           text "Hello, Flex World!",
+        #                size: :xl,
+        #                color: "#FF0000",
+        #                wrap: true do
+        #                  message "Tell me more about text", label: "More info"
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # == Example: Creating a text component with spans
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Span Example" do
+        #       bubble do
+        #         body do
+        #           text "This message has styled spans:" do
+        #             span "Red", color: "#FF0000"
+        #             span " and ", size: :sm
+        #             span "Bold", weight: :bold
         #           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.
+        # === Example: Emphasising a heading and truncating a long body
+        #
+        #   Line::Message::Builder.with do
+        #     flex alt_text: "Article" do
+        #       bubble do
+        #         body do
+        #           text "Ruby Taiwan Meetup", weight: :bold, size: :xl
+        #           text long_article_body, wrap: true, max_lines: 3
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # See also:
+        # - https://developers.line.biz/en/reference/messaging-api/#text
+        # - Actionable for making the text 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::Shared for common +size+ keywords (e.g., +:xl+, +:sm+)
+        # - Size::AdjustMode for +adjust_mode+ property
         class Text < Line::Message::Builder::Base
           include Actionable           # Enables defining an action for the text.
           include Position::Horizontal # Adds `align` option.
@@ -47,60 +82,167 @@ module Line
           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.
+          # The actual text content to be displayed (required attribute).
           attr_reader :text
 
-          # Specifies whether the text should wrap or be truncated if it exceeds
+          # Array of Span components for styled text segments.
+          attr_reader :contents
+
+          # :method: wrap
+          # :call-seq:
+          #   wrap() -> Boolean
+          #   wrap(value) -> Boolean
+          #
+          # Sets or gets 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.
+          #
+          # [value]
+          #   +true+ to enable text wrapping, +false+ (default) to disable
           option :wrap, default: false
 
-          # 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.
+          # :method: line_spacing
+          # :call-seq:
+          #   line_spacing() -> String or nil
+          #   line_spacing(value) -> String
+          #
+          # Sets or gets the spacing between lines of text.
+          # Can be a pixel value or a keyword.
+          #
+          # [value]
+          #   The line spacing value (e.g., <code>"5px"</code>)
           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.
+          # :method: color
+          # :call-seq:
+          #   color() -> String or nil
+          #   color(value) -> String
+          #
+          # Sets or gets the color of the text.
+          #
+          # [value]
+          #   Hexadecimal color code (e.g., <code>"#RRGGBB"</code>, <code>"#RRGGBBAA"</code>)
           option :color, default: nil
 
+          # :method: weight
+          # :call-seq:
+          #   weight() -> Symbol or nil
+          #   weight(value) -> Symbol
+          #
+          # Sets or gets the font weight of the text.
+          #
+          # [value]
+          #   <code>:regular</code> (default) or <code>:bold</code>
+          option :weight, default: nil, validator: Validators::Enum.new(:regular, :bold)
+
+          # :method: max_lines
+          # :call-seq:
+          #   max_lines() -> Integer or nil
+          #   max_lines(value) -> Integer
+          #
+          # Sets or gets the maximum number of lines to display. Text exceeding
+          # this number of lines ends in an ellipsis. A value of +0+ displays the
+          # entire text.
+          #
+          # [value]
+          #   The maximum number of lines
+          option :max_lines, default: nil # API key: maxLines
+
+          # :method: style
+          # :call-seq:
+          #   style() -> Symbol or nil
+          #   style(value) -> Symbol
+          #
+          # Sets or gets the font style of the text.
+          #
+          # [value]
+          #   <code>:normal</code> (default) or <code>:italic</code>
+          option :style, default: nil, validator: Validators::Enum.new(:normal, :italic)
+
+          # :method: decoration
+          # :call-seq:
+          #   decoration() -> Symbol or nil
+          #   decoration(value) -> Symbol
+          #
+          # Sets or gets the decoration of the text. A decoration set here cannot
+          # be overwritten by the +decoration+ of a nested Span.
+          #
+          # [value]
+          #   <code>:none</code> (default), <code>:underline</code> or
+          #   <code>:"line-through"</code>
+          option :decoration, default: nil, validator: Validators::Enum.new(:none, :underline, :"line-through")
+
+          # :method: scaling
+          # :call-seq:
+          #   scaling() -> Boolean or nil
+          #   scaling(value) -> Boolean
+          #
+          # Sets or gets whether the font size follows the font size setting of
+          # the LINE app. Spans nested in this text are scaled as well.
+          #
+          # [value]
+          #   +true+ to scale the font size, +false+ (default) to keep it fixed
+          option :scaling, default: nil
+
           # 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_content]
+          #   The text to display (required)
+          # [context]
+          #   An optional context for the builder
+          # [options]
+          #   A hash of options to set instance variables
+          #   (e.g., +:wrap+, +:color+, +:size+, and options from included modules)
+          # [block]
+          #   An optional block, typically used to define an action for the text
+          #
+          # Raises RequiredError if +text_content+ is nil (in +to_h+).
+          def initialize(text_content = nil, context: nil, **options, &)
             @text = text_content # The text content is mandatory.
+            @contents = []       # Initialize contents for spans, if any.
 
             super(context: context, **options, &) # Sets options and evals block (for action).
           end
 
-          # A convenience DSL method to set the `wrap` property to `true`.
+          # A convenience DSL method to set the +wrap+ property to +true+.
+          #
+          # == Example
           #
-          # @example
           #   text_component.text "Long text..."
           #   text_component.wrap! # Enables text wrapping
-          #
-          # @return [true]
           def wrap!
             wrap(true) # Use the setter generated by `option`
           end
 
+          # Adds a Span component to this text component's contents.
+          #
+          # Spans allow different styling for parts of the text, such as color,
+          # weight, size, and decoration.
+          #
+          # [text_content]
+          #   The span text content
+          # [options]
+          #   Options for the span (see Span)
+          # [block]
+          #   An optional block for advanced span configuration
+          #
+          # == Example
+          #
+          #   text "Message with spans:" do
+          #     span "Important", color: "#FF0000", weight: :bold
+          #     span " normal text"
+          #   end
+          def span(text_content, **options, &)
+            @contents << Span.new(text_content, context: @context, **options, &)
+          end
+
+          # :nodoc:
+          def any_content?
+            !contents.empty? || !text.nil?
+          end
+
+          # :nodoc:
           def to_h
-            raise RequiredError, "text content is required for a text component" if text.nil?
+            raise RequiredError, "text content is required for a text component" unless any_content?
 
             return to_sdkv2 if context.sdkv2?
 
@@ -109,13 +251,20 @@ module Line
 
           private
 
+          # :nodoc:
           def to_api # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             {
               type: "text",
               text: text,
+              contents: contents.map(&:to_h), # Convert spans to hash
               wrap: wrap,               # From option
               color: color,             # From option
               lineSpacing: line_spacing, # From option (maps to API key)
+              weight: weight,           # From option
+              maxLines: max_lines,      # From option (maps to API key)
+              style: style,             # From option
+              decoration: decoration,   # From option
+              scaling: scaling,         # From option
               # Position::Horizontal & Position::Vertical
               align: align,     # From Position::Horizontal
               gravity: gravity, # From Position::Vertical
@@ -137,13 +286,20 @@ module Line
             }.compact
           end
 
+          # :nodoc:
           def to_sdkv2 # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             {
               type: "text",
               text: text,
+              contents: contents.map(&:to_h), # Convert spans to hash
               wrap: wrap,               # From option
               color: color,             # From option
               line_spacing: line_spacing, # From option (maps to API key)
+              weight: weight,           # From option
+              max_lines: max_lines,     # From option (maps to API key)
+              style: style,             # From option
+              decoration: decoration,   # From option
+              scaling: scaling,         # From option
               # Position::Horizontal & Position::Vertical
               align: align,     # From Position::Horizontal
               gravity: gravity, # From Position::Vertical

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

@@ -3,46 +3,48 @@
 module Line
   module Message
     module Builder
-      # The `Line::Message::Builder::Flex` module serves as the primary namespace
+      # The Line::Message::Builder::Flex module serves as the primary namespace
       # for all classes, modules, and components related to the construction of
-      # LINE Flex Messages within the `line-message-builder` gem.
+      # LINE Flex Messages within the +line-message-builder+ gem.
       #
       # Flex Messages are highly customizable messages that can display rich content
       # with various layouts, components, and interactive elements. This module
       # organizes the DSL for building these messages.
       #
-      # This file (`lib/line/message/builder/flex.rb`) is responsible for loading
-      # all necessary sub-components and builder logic for Flex Messages, such as:
-      # - {Flex::Builder}: The main class used to construct a complete Flex Message object.
-      # - Container components: {Flex::Bubble}, {Flex::Carousel}.
-      # - Basic components: {Flex::Box}, {Flex::Text}, {Flex::Button}, {Flex::Image}.
-      # - Mixin modules for shared functionality: {Flex::Actionable},
-      #   modules within {Flex::Position} and {Flex::Size}.
-      # - The partial system: {Flex::HasPartial} and {Flex::Partial}.
+      # This file is responsible for loading all necessary sub-components and builder
+      # logic for Flex Messages, such as:
+      # - Flex::Builder - The main class used to construct a complete Flex Message object
+      # - Container components: Flex::Bubble, Flex::Carousel
+      # - Basic components: Flex::Box, Flex::Text, Flex::Button, Flex::Image
+      # - Mixin modules for shared functionality: Flex::Actionable, modules within
+      #   Flex::Position and Flex::Size
+      # - The partial system: Flex::HasPartial and Flex::Partial
       #
       # While this module itself is a namespace, the actual process of building a
-      # Flex Message typically starts within a {Line::Message::Builder::Container}
-      # block, by calling the `flex` method on the container. This method then
-      # instantiates and uses {Flex::Builder} to define the Flex Message structure.
+      # Flex Message typically starts within a Line::Message::Builder::Container
+      # block, by calling the +flex+ method on the container. This method then
+      # instantiates and uses Flex::Builder to define the Flex Message structure.
       #
-      # @example How a Flex Message is typically initiated (conceptual)
-      #   Line::Message::Builder.with do |root_container|
-      #     # This `flex` call on root_container would utilize Flex::Builder
-      #     root_container.flex(alt_text: "My Flex Message") do |flex_msg_builder|
-      #       flex_msg_builder.bubble do |bubble_builder|
+      # == Example
+      #
+      #   Line::Message::Builder.with do
+      #     # This +flex+ call on root_container would utilize Flex::Builder
+      #     flex alt_text: "My Flex Message"  do
+      #       bubble do
       #         # ... define bubble content ...
       #       end
       #     end
       #   end
       #
-      # @see Flex::Builder For the main Flex Message construction entry point.
-      # @see Flex::Bubble
-      # @see Flex::Carousel
-      # @see Flex::Box
-      # @see Flex::Text
-      # @see Flex::Button
-      # @see Flex::Image
-      # @see https://developers.line.biz/en/docs/messaging-api/using-flex-messages/
+      # See also:
+      # - Flex::Builder - For the main Flex Message construction entry point
+      # - Flex::Bubble
+      # - Flex::Carousel
+      # - Flex::Box
+      # - Flex::Text
+      # - Flex::Button
+      # - Flex::Image
+      # - https://developers.line.biz/en/docs/messaging-api/using-flex-messages/
       module Flex
         # Main builder for the entire Flex Message object
         require_relative "flex/builder"
@@ -64,6 +66,9 @@ module Line
         require_relative "flex/text"     # Text display
         require_relative "flex/button"   # Interactive button
         require_relative "flex/image"    # Image display
+        require_relative "flex/icon"     # Icon decorating adjacent text
+        require_relative "flex/separator" # Visual separator
+        require_relative "flex/span" # Text span for styling parts of text
       end
     end
   end