inkpen 0.7.1

data/lib/inkpen/extensions/task_list.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Task List extension for TipTap.
+    #
+    # Enables interactive checkbox/task list functionality. Users can
+    # create todo lists with checkable items that persist their state.
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::TaskList.new
+    #
+    # @example With nested tasks disabled
+    #   extension = Inkpen::Extensions::TaskList.new(
+    #     nested: false,
+    #     item_class: "my-task-item"
+    #   )
+    #
+    # @see https://tiptap.dev/docs/examples/tasks
+    # @author Inkpen Team
+    # @since 0.2.0
+    #
+    class TaskList < Base
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :task_list
+      #
+      def name
+        :task_list
+      end
+
+      ##
+      # Whether task lists can be nested.
+      #
+      # @return [Boolean] true to allow nested task lists
+      #
+      def nested?
+        options.fetch(:nested, true)
+      end
+
+      ##
+      # CSS class applied to task list container.
+      #
+      # @return [String] CSS class name
+      #
+      def list_class
+        options.fetch(:list_class, "inkpen-task-list")
+      end
+
+      ##
+      # CSS class applied to individual task items.
+      #
+      # @return [String] CSS class name
+      #
+      def item_class
+        options.fetch(:item_class, "inkpen-task-item")
+      end
+
+      ##
+      # CSS class applied to checked task items.
+      #
+      # @return [String] CSS class name
+      #
+      def checked_class
+        options.fetch(:checked_class, "inkpen-task-checked")
+      end
+
+      ##
+      # CSS class applied to the checkbox element.
+      #
+      # @return [String] CSS class name
+      #
+      def checkbox_class
+        options.fetch(:checkbox_class, "inkpen-task-checkbox")
+      end
+
+      ##
+      # HTML attributes for the task list element.
+      #
+      # @return [Hash] HTML attributes
+      #
+      def html_attributes
+        options.fetch(:html_attributes, { class: list_class })
+      end
+
+      ##
+      # HTML attributes for task item elements.
+      #
+      # @return [Hash] HTML attributes
+      #
+      def item_html_attributes
+        options.fetch(:item_html_attributes, { class: item_class })
+      end
+
+      ##
+      # Whether clicking on the text toggles the checkbox.
+      #
+      # @return [Boolean] true if text click toggles checkbox
+      #
+      def text_toggle?
+        options.fetch(:text_toggle, false)
+      end
+
+      ##
+      # Keyboard shortcut to create a task list.
+      #
+      # @return [String] keyboard shortcut
+      #
+      def keyboard_shortcut
+        options.fetch(:keyboard_shortcut, "Mod-Shift-9")
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        {
+          nested: nested?,
+          listClass: list_class,
+          itemClass: item_class,
+          checkedClass: checked_class,
+          checkboxClass: checkbox_class,
+          HTMLAttributes: html_attributes,
+          itemHTMLAttributes: item_html_attributes,
+          textToggle: text_toggle?,
+          keyboardShortcut: keyboard_shortcut
+        }
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          nested: true,
+          text_toggle: false,
+          keyboard_shortcut: "Mod-Shift-9"
+        )
+      end
+    end
+  end
+end

data/lib/inkpen/sticky_toolbar.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Inkpen
+  ##
+  # PORO representing sticky toolbar configuration.
+  #
+  # The StickyToolbar provides block and media insertion controls that
+  # remain fixed on screen. It's separate from the text formatting
+  # toolbar and focused on inserting new content blocks.
+  #
+  # Supports horizontal (bottom) and vertical (left/right) layouts.
+  #
+  # @example Basic bottom toolbar
+  #   sticky_toolbar = Inkpen::StickyToolbar.new(position: :bottom)
+  #
+  # @example Custom buttons
+  #   sticky_toolbar = Inkpen::StickyToolbar.new(
+  #     position: :bottom,
+  #     buttons: [:table, :code_block, :image, :divider]
+  #   )
+  #
+  # @example In editor helper
+  #   <%= inkpen_editor name: "post[body]",
+  #       sticky_toolbar: Inkpen::StickyToolbar.new(position: :right) %>
+  #
+  # @see Inkpen::Toolbar For text formatting toolbar
+  #
+  # @author Nauman Tariq
+  # @since 0.2.1
+  #
+  class StickyToolbar
+    ##
+    # @!attribute [r] position
+    #   @return [Symbol] toolbar position (:bottom, :left, :right)
+    #
+    # @!attribute [r] buttons
+    #   @return [Array<Symbol>] list of toolbar buttons
+    #
+    # @!attribute [r] widget_types
+    #   @return [Array<String>] available widget types for widget picker
+    #
+    attr_reader :position, :buttons, :widget_types
+
+    ##
+    # Valid toolbar positions.
+    # @return [Array<Symbol>]
+    POSITIONS = %i[bottom left right].freeze
+
+    ##
+    # Block insertion buttons.
+    # @return [Array<Symbol>]
+    BLOCK_BUTTONS = %i[table code_block blockquote horizontal_rule task_list].freeze
+
+    ##
+    # Media insertion buttons.
+    # @return [Array<Symbol>]
+    MEDIA_BUTTONS = %i[image youtube embed].freeze
+
+    ##
+    # Widget insertion buttons (opens modal picker).
+    # @return [Array<Symbol>]
+    WIDGET_BUTTONS = %i[widget].freeze
+
+    ##
+    # Preset with block buttons only.
+    # @return [Array<Symbol>]
+    PRESET_BLOCKS = BLOCK_BUTTONS.freeze
+
+    ##
+    # Preset with media buttons only.
+    # @return [Array<Symbol>]
+    PRESET_MEDIA = MEDIA_BUTTONS.freeze
+
+    ##
+    # Full preset with all buttons.
+    # @return [Array<Symbol>]
+    PRESET_FULL = (BLOCK_BUTTONS + MEDIA_BUTTONS + WIDGET_BUTTONS).freeze
+
+    ##
+    # Initialize a new sticky toolbar configuration.
+    #
+    # @param position [Symbol] toolbar position (:bottom, :left, :right)
+    # @param buttons [Array<Symbol>, nil] custom button list
+    # @param widget_types [Array<String>, nil] widget types for picker
+    # @param enabled [Boolean] whether the sticky toolbar is enabled
+    #
+    def initialize(position: :bottom, buttons: nil, widget_types: nil, enabled: true)
+      @position = validate_position(position)
+      @buttons = buttons || PRESET_FULL
+      @widget_types = widget_types || default_widget_types
+      @enabled = enabled
+    end
+
+    ##
+    # Check if the sticky toolbar is enabled.
+    #
+    # @return [Boolean] true if enabled
+    #
+    def enabled?
+      @enabled
+    end
+
+    ##
+    # Check if toolbar uses vertical layout (left or right).
+    #
+    # @return [Boolean] true if vertical
+    #
+    def vertical?
+      %i[left right].include?(position)
+    end
+
+    ##
+    # Check if toolbar uses horizontal layout (bottom).
+    #
+    # @return [Boolean] true if horizontal
+    #
+    def horizontal?
+      position == :bottom
+    end
+
+    ##
+    # Generate data attributes for Stimulus controller.
+    #
+    # @return [Hash] data attributes hash
+    #
+    def data_attributes
+      {
+        "inkpen--sticky-toolbar-position-value" => position.to_s,
+        "inkpen--sticky-toolbar-buttons-value" => buttons.to_json,
+        "inkpen--sticky-toolbar-widget-types-value" => widget_types.to_json,
+        "inkpen--sticky-toolbar-vertical-value" => vertical?.to_s
+      }
+    end
+
+    private
+
+    ##
+    # Validate and normalize position value.
+    #
+    # @param pos [Symbol, String] position to validate
+    # @return [Symbol] validated position
+    #
+    def validate_position(pos)
+      pos = pos.to_sym
+      POSITIONS.include?(pos) ? pos : :bottom
+    end
+
+    ##
+    # Default widget types for the widget picker.
+    #
+    # @return [Array<String>] widget type names
+    #
+    def default_widget_types
+      %w[form gallery poll]
+    end
+  end
+end

data/lib/inkpen/toolbar.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Inkpen
+  ##
+  # PORO representing toolbar configuration.
+  #
+  # The Toolbar class configures the floating or fixed toolbar that
+  # appears when text is selected (floating) or at the top of the
+  # editor (fixed).
+  #
+  # @example Basic floating toolbar
+  #   toolbar = Inkpen::Toolbar.new(style: :floating)
+  #
+  # @example Custom button set
+  #   toolbar = Inkpen::Toolbar.new(
+  #     style: :fixed,
+  #     buttons: [:bold, :italic, :link, :heading]
+  #   )
+  #
+  # @example Using presets
+  #   toolbar = Inkpen::Toolbar.new(
+  #     style: :floating,
+  #     buttons: Inkpen::Toolbar::PRESET_MINIMAL
+  #   )
+  #
+  # @see Inkpen::StickyToolbar For block insertion toolbar
+  #
+  # @author Nauman Tariq
+  # @since 0.1.0
+  #
+  class Toolbar
+    ##
+    # @!attribute [r] style
+    #   @return [Symbol] toolbar display style (:floating, :fixed, :none)
+    #
+    # @!attribute [r] buttons
+    #   @return [Array<Symbol>] list of toolbar buttons
+    #
+    # @!attribute [r] position
+    #   @return [Symbol] toolbar position (:top, :bottom)
+    #
+    attr_reader :style, :buttons, :position
+
+    ##
+    # Text formatting buttons (bold, italic, strike, underline).
+    # @return [Array<Symbol>]
+    FORMATTING_BUTTONS = %i[bold italic strike underline].freeze
+
+    ##
+    # Block-level formatting buttons.
+    # @return [Array<Symbol>]
+    BLOCK_BUTTONS = %i[heading bullet_list ordered_list blockquote code_block].freeze
+
+    ##
+    # Content insertion buttons.
+    # @return [Array<Symbol>]
+    INSERT_BUTTONS = %i[link image table horizontal_rule].freeze
+
+    ##
+    # Minimal preset (bold, italic, link).
+    # @return [Array<Symbol>]
+    PRESET_MINIMAL = %i[bold italic link].freeze
+
+    ##
+    # Standard preset with common formatting options.
+    # @return [Array<Symbol>]
+    PRESET_STANDARD = (FORMATTING_BUTTONS + %i[link heading bullet_list ordered_list blockquote]).freeze
+
+    ##
+    # Full preset with all available buttons.
+    # @return [Array<Symbol>]
+    PRESET_FULL = (FORMATTING_BUTTONS + BLOCK_BUTTONS + INSERT_BUTTONS).freeze
+
+    ##
+    # Initialize a new toolbar configuration.
+    #
+    # @param style [Symbol] toolbar style (:floating, :fixed, :none)
+    # @param buttons [Array<Symbol>, nil] custom button list (defaults to preset)
+    # @param position [Symbol] toolbar position (:top, :bottom)
+    #
+    def initialize(style: :floating, buttons: nil, position: :top)
+      @style = style.to_sym
+      @buttons = buttons || default_buttons_for_style
+      @position = position.to_sym
+    end
+
+    ##
+    # Check if toolbar uses floating (bubble menu) style.
+    #
+    # @return [Boolean] true if floating style
+    #
+    def floating?
+      style == :floating
+    end
+
+    ##
+    # Check if toolbar uses fixed style.
+    #
+    # @return [Boolean] true if fixed style
+    #
+    def fixed?
+      style == :fixed
+    end
+
+    ##
+    # Check if toolbar is hidden.
+    #
+    # @return [Boolean] true if toolbar is hidden
+    #
+    def hidden?
+      style == :none
+    end
+
+    ##
+    # Generate data attributes for Stimulus controller.
+    #
+    # @return [Hash] data attributes hash
+    #
+    def data_attributes
+      {
+        "inkpen--toolbar-style-value" => style.to_s,
+        "inkpen--toolbar-buttons-value" => buttons.to_json,
+        "inkpen--toolbar-position-value" => position.to_s
+      }
+    end
+
+    private
+
+    ##
+    # Get default buttons based on toolbar style.
+    #
+    # @return [Array<Symbol>] default button list
+    #
+    def default_buttons_for_style
+      case style
+      when :floating
+        PRESET_STANDARD
+      when :fixed
+        PRESET_FULL
+      else
+        []
+      end
+    end
+  end
+end

data/lib/inkpen/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Inkpen
+  VERSION = "0.7.1"
+end

data/lib/inkpen.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "inkpen/version"
+require_relative "inkpen/engine"
+require_relative "inkpen/configuration"
+require_relative "inkpen/editor"
+require_relative "inkpen/toolbar"
+require_relative "inkpen/sticky_toolbar"
+require_relative "inkpen/markdown_mode"
+
+# Extensions
+require_relative "inkpen/extensions/base"
+require_relative "inkpen/extensions/forced_document"
+require_relative "inkpen/extensions/mention"
+require_relative "inkpen/extensions/code_block_syntax"
+require_relative "inkpen/extensions/table"
+require_relative "inkpen/extensions/task_list"
+require_relative "inkpen/extensions/slash_commands"
+require_relative "inkpen/extensions/section"
+require_relative "inkpen/extensions/preformatted"
+
+##
+# Inkpen is a TipTap-based rich text editor gem for Rails applications.
+#
+# It provides a customizable WYSIWYG editor with Notion-like features including:
+# - Block-based editing with drag & drop
+# - Slash commands for quick block insertion
+# - Multiple toolbar options (floating, fixed, sticky)
+# - 16+ custom TipTap extensions
+# - Export to Markdown, HTML, and PDF
+#
+# @example Basic usage with Rails form
+#   <%= inkpen_editor form, :content %>
+#
+# @example With configuration
+#   Inkpen.configure do |config|
+#     config.toolbar = :floating
+#     config.extensions = [:bold, :italic, :link, :slash_commands]
+#     config.placeholder = "Start writing..."
+#   end
+#
+# @example Full-featured editor
+#   <%= inkpen_editor form, :content,
+#       toolbar: :sticky,
+#       extensions: [:slash_commands, :block_gutter, :drag_handle, :export_commands] %>
+#
+# @see Inkpen::Configuration Global configuration options
+# @see Inkpen::Editor Editor instance configuration
+# @see Inkpen::Extensions Extension system
+#
+# @author Nauman Tariq
+# @since 0.1.0
+#
+module Inkpen
+  ##
+  # Base error class for all Inkpen errors.
+  #
+  class Error < StandardError; end
+
+  class << self
+    ##
+    # @return [Configuration] the global configuration instance
+    attr_writer :configuration
+
+    ##
+    # Returns the global configuration instance.
+    #
+    # @return [Configuration] the configuration object
+    #
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    ##
+    # Configure Inkpen globally.
+    #
+    # @yield [config] Yields the configuration object for modification
+    # @yieldparam config [Configuration] the configuration object
+    #
+    # @example
+    #   Inkpen.configure do |config|
+    #     config.toolbar = :floating
+    #     config.extensions = [:bold, :italic, :link]
+    #   end
+    #
+    def configure
+      yield(configuration)
+    end
+
+    ##
+    # Reset configuration to defaults.
+    #
+    # Useful for testing or reinitializing the editor configuration.
+    #
+    # @return [Configuration] the new configuration object
+    #
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/sig/inkpen.rbs

@@ -0,0 +1,4 @@
+module Inkpen
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end