inkpen 0.7.1

data/lib/inkpen/extensions/mention.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Mention extension for @mentions functionality.
+    #
+    # Enables users to mention other users or entities using the @ symbol.
+    # When triggered, a popup appears with suggestions that can be filtered
+    # by typing.
+    #
+    # The suggestion data is fetched from a configurable endpoint.
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::Mention.new(
+    #     search_url: "/api/users/search"
+    #   )
+    #
+    # @example With custom trigger and styling
+    #   extension = Inkpen::Extensions::Mention.new(
+    #     search_url: "/api/users/search",
+    #     trigger: "@",
+    #     suggestion_class: "mention-suggestion",
+    #     item_class: "mention-item"
+    #   )
+    #
+    # @see https://tiptap.dev/docs/examples/advanced/mentions
+    # @author Inkpen Team
+    # @since 0.2.0
+    #
+    class Mention < Base
+      ##
+      # Default trigger character for mentions.
+      DEFAULT_TRIGGER = "@"
+
+      ##
+      # Default minimum characters to start searching.
+      DEFAULT_MIN_CHARS = 1
+
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :mention
+      #
+      def name
+        :mention
+      end
+
+      ##
+      # The character that triggers the mention popup.
+      #
+      # @return [String] trigger character (default: "@")
+      #
+      def trigger
+        options.fetch(:trigger, DEFAULT_TRIGGER)
+      end
+
+      ##
+      # URL endpoint for fetching mention suggestions.
+      #
+      # The endpoint receives a `query` parameter with the search text.
+      # Expected response format: [{ id: 1, label: "Username", ... }]
+      #
+      # @return [String, nil] search URL or nil if using static items
+      #
+      def search_url
+        options[:search_url]
+      end
+
+      ##
+      # Static items to show in the suggestion popup.
+      #
+      # Use this instead of search_url for fixed suggestion lists.
+      #
+      # @return [Array<Hash>, nil] array of suggestion items
+      #
+      def items
+        options[:items]
+      end
+
+      ##
+      # Minimum characters before triggering search.
+      #
+      # @return [Integer] minimum character count
+      #
+      def min_chars
+        options.fetch(:min_chars, DEFAULT_MIN_CHARS)
+      end
+
+      ##
+      # CSS class for the suggestion popup container.
+      #
+      # @return [String] CSS class name
+      #
+      def suggestion_class
+        options.fetch(:suggestion_class, "inkpen-mention-suggestions")
+      end
+
+      ##
+      # CSS class for individual suggestion items.
+      #
+      # @return [String] CSS class name
+      #
+      def item_class
+        options.fetch(:item_class, "inkpen-mention-item")
+      end
+
+      ##
+      # Whether to allow creating new mentions not in the suggestion list.
+      #
+      # @return [Boolean] true to allow custom mentions
+      #
+      def allow_custom?
+        options.fetch(:allow_custom, false)
+      end
+
+      ##
+      # HTML attributes rendered on the mention node.
+      #
+      # @return [Hash] HTML attributes
+      #
+      def html_attributes
+        options.fetch(:html_attributes, { class: "inkpen-mention" })
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        {
+          trigger: trigger,
+          searchUrl: search_url,
+          items: items,
+          minChars: min_chars,
+          suggestionClass: suggestion_class,
+          itemClass: item_class,
+          allowCustom: allow_custom?,
+          HTMLAttributes: html_attributes
+        }.compact
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          trigger: DEFAULT_TRIGGER,
+          min_chars: DEFAULT_MIN_CHARS,
+          allow_custom: false
+        )
+      end
+    end
+  end
+end

data/lib/inkpen/extensions/preformatted.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Preformatted text extension for TipTap.
+    #
+    # Plain text block that preserves whitespace exactly as typed.
+    # Perfect for ASCII art, ASCII tables, diagrams, and any content
+    # that requires precise character alignment.
+    #
+    # Unlike CodeBlock, this has NO syntax highlighting - just pure
+    # monospace text with preserved whitespace.
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::Preformatted.new
+    #
+    # @example With custom options
+    #   extension = Inkpen::Extensions::Preformatted.new(
+    #     show_line_numbers: false,
+    #     wrap_lines: false
+    #   )
+    #
+    # @see https://tiptap.dev/docs/editor/api/nodes
+    # @author Inkpen Team
+    # @since 0.3.0
+    #
+    class Preformatted < Base
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :preformatted
+      #
+      def name
+        :preformatted
+      end
+
+      ##
+      # Whether to show line numbers.
+      #
+      # @return [Boolean] true to show line numbers
+      #
+      def show_line_numbers?
+        options.fetch(:show_line_numbers, false)
+      end
+
+      ##
+      # Whether to wrap long lines.
+      #
+      # @return [Boolean] true to wrap lines
+      #
+      def wrap_lines?
+        options.fetch(:wrap_lines, false)
+      end
+
+      ##
+      # Tab size in spaces.
+      #
+      # @return [Integer] number of spaces per tab
+      #
+      def tab_size
+        options.fetch(:tab_size, 4)
+      end
+
+      ##
+      # Whether to show a label/badge.
+      #
+      # @return [Boolean] true to show label
+      #
+      def show_label?
+        options.fetch(:show_label, true)
+      end
+
+      ##
+      # Custom label text.
+      #
+      # @return [String] the label text
+      #
+      def label_text
+        options.fetch(:label_text, "Plain Text")
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        {
+          showLineNumbers: show_line_numbers?,
+          wrapLines: wrap_lines?,
+          tabSize: tab_size,
+          showLabel: show_label?,
+          labelText: label_text
+        }
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          show_line_numbers: false,
+          wrap_lines: false,
+          tab_size: 4,
+          show_label: true,
+          label_text: "Plain Text"
+        )
+      end
+    end
+  end
+end

data/lib/inkpen/extensions/section.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Section extension for TipTap.
+    #
+    # Block-level container that controls content width and vertical spacing.
+    # Useful for page-builder style layouts where different sections need
+    # different widths (narrow for reading, wide for media, full for heroes).
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::Section.new
+    #
+    # @example With custom options
+    #   extension = Inkpen::Extensions::Section.new(
+    #     default_width: "wide",
+    #     default_spacing: "spacious",
+    #     show_controls: true
+    #   )
+    #
+    # @see https://tiptap.dev/docs/editor/api/nodes
+    # @author Inkpen Team
+    # @since 0.3.0
+    #
+    class Section < Base
+      ##
+      # Available width presets with their CSS values.
+      WIDTH_PRESETS = {
+        narrow: { max_width: "560px", label: "Narrow" },
+        default: { max_width: "680px", label: "Default" },
+        wide: { max_width: "900px", label: "Wide" },
+        full: { max_width: "100%", label: "Full" }
+      }.freeze
+
+      ##
+      # Available spacing presets with their CSS values.
+      SPACING_PRESETS = {
+        compact: { padding: "1rem 0", label: "Compact" },
+        normal: { padding: "2rem 0", label: "Normal" },
+        spacious: { padding: "4rem 0", label: "Spacious" }
+      }.freeze
+
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :section
+      #
+      def name
+        :section
+      end
+
+      ##
+      # Default width preset for new sections.
+      #
+      # @return [String] the default width preset key
+      #
+      def default_width
+        options.fetch(:default_width, "default")
+      end
+
+      ##
+      # Default spacing preset for new sections.
+      #
+      # @return [String] the default spacing preset key
+      #
+      def default_spacing
+        options.fetch(:default_spacing, "normal")
+      end
+
+      ##
+      # Whether to show the section controls UI.
+      #
+      # @return [Boolean] true to show controls
+      #
+      def show_controls?
+        options.fetch(:show_controls, true)
+      end
+
+      ##
+      # Available width presets.
+      #
+      # @return [Hash] width presets with max_width and label
+      #
+      def width_presets
+        custom_presets = options[:width_presets] || {}
+        WIDTH_PRESETS.merge(custom_presets.transform_keys(&:to_sym))
+      end
+
+      ##
+      # Available spacing presets.
+      #
+      # @return [Hash] spacing presets with padding and label
+      #
+      def spacing_presets
+        custom_presets = options[:spacing_presets] || {}
+        SPACING_PRESETS.merge(custom_presets.transform_keys(&:to_sym))
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        {
+          defaultWidth: default_width,
+          defaultSpacing: default_spacing,
+          showControls: show_controls?,
+          widthPresets: serialize_presets(width_presets),
+          spacingPresets: serialize_presets(spacing_presets)
+        }
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          default_width: "default",
+          default_spacing: "normal",
+          show_controls: true
+        )
+      end
+
+      ##
+      # Convert Ruby-style presets to JavaScript camelCase.
+      #
+      def serialize_presets(presets)
+        presets.transform_values do |preset|
+          preset.transform_keys { |k| camelize(k.to_s) }
+        end
+      end
+
+      def camelize(string)
+        string.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+      end
+    end
+  end
+end

data/lib/inkpen/extensions/slash_commands.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    # SlashCommands Extension
+    #
+    # Adds "/" command palette for quick insertion of blocks and formatting.
+    # Similar to Notion's slash commands or Dropbox Paper's "/" menu.
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::SlashCommands.new
+    #
+    # @example With custom commands
+    #   extension = Inkpen::Extensions::SlashCommands.new(
+    #     trigger: "/",
+    #     commands: [
+    #       { name: "heading1", label: "Heading 1", icon: "h1", group: "Basic" },
+    #       { name: "heading2", label: "Heading 2", icon: "h2", group: "Basic" },
+    #       { name: "bullet_list", label: "Bullet List", icon: "list", group: "Lists" },
+    #       { name: "code_block", label: "Code Block", icon: "code", group: "Advanced" }
+    #     ],
+    #     groups: ["Basic", "Lists", "Media", "Advanced"],
+    #     max_suggestions: 10,
+    #     allow_filtering: true
+    #   )
+    #
+    class SlashCommands < Base
+      # Default command set matching Notion/Paper experience
+      DEFAULT_COMMANDS = [
+        # Text blocks
+        { name: "paragraph", label: "Text", description: "Plain text block", icon: "text", group: "Basic", shortcut: nil },
+        { name: "heading1", label: "Heading 1", description: "Large heading", icon: "h1", group: "Basic", shortcut: "#" },
+        { name: "heading2", label: "Heading 2", description: "Medium heading", icon: "h2", group: "Basic", shortcut: "##" },
+        { name: "heading3", label: "Heading 3", description: "Small heading", icon: "h3", group: "Basic", shortcut: "###" },
+
+        # Lists
+        { name: "bullet_list", label: "Bullet List", description: "Unordered list", icon: "list", group: "Lists", shortcut: "-" },
+        { name: "ordered_list", label: "Numbered List", description: "Ordered list", icon: "list-ordered", group: "Lists", shortcut: "1." },
+        { name: "task_list", label: "Task List", description: "Checklist with checkboxes", icon: "check-square", group: "Lists", shortcut: "[]" },
+
+        # Blocks
+        { name: "blockquote", label: "Quote", description: "Quote block", icon: "quote", group: "Blocks", shortcut: ">" },
+        { name: "code_block", label: "Code Block", description: "Code with syntax highlighting", icon: "code", group: "Blocks", shortcut: "```" },
+        { name: "horizontal_rule", label: "Divider", description: "Horizontal line", icon: "minus", group: "Blocks", shortcut: "---" },
+
+        # Media
+        { name: "image", label: "Image", description: "Upload or embed an image", icon: "image", group: "Media", shortcut: nil },
+        { name: "youtube", label: "YouTube", description: "Embed a YouTube video", icon: "youtube", group: "Media", shortcut: nil },
+
+        # Advanced
+        { name: "table", label: "Table", description: "Insert a table", icon: "table", group: "Advanced", shortcut: nil },
+        { name: "callout", label: "Callout", description: "Highlighted callout box", icon: "alert-circle", group: "Advanced", shortcut: nil },
+        { name: "section", label: "Section", description: "Page section with width control", icon: "layout", group: "Advanced", shortcut: nil },
+        { name: "preformatted", label: "Plain Text", description: "Preformatted text for ASCII art", icon: "file-text", group: "Advanced", shortcut: nil }
+      ].freeze
+
+      DEFAULT_GROUPS = %w[Basic Lists Blocks Media Advanced].freeze
+
+      def name
+        :slash_commands
+      end
+
+      def to_config
+        {
+          trigger: options[:trigger],
+          commands: options[:commands],
+          groups: options[:groups],
+          maxSuggestions: options[:max_suggestions],
+          allowFiltering: options[:allow_filtering],
+          showIcons: options[:show_icons],
+          showDescriptions: options[:show_descriptions],
+          showShortcuts: options[:show_shortcuts],
+          suggestionClass: options[:suggestion_class],
+          itemClass: options[:item_class],
+          activeClass: options[:active_class],
+          groupClass: options[:group_class]
+        }.compact
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          trigger: "/",
+          commands: DEFAULT_COMMANDS,
+          groups: DEFAULT_GROUPS,
+          max_suggestions: 10,
+          allow_filtering: true,
+          show_icons: true,
+          show_descriptions: true,
+          show_shortcuts: false,
+          suggestion_class: "inkpen-slash-menu",
+          item_class: "inkpen-slash-item",
+          active_class: "is-selected",
+          group_class: "inkpen-slash-group"
+        )
+      end
+    end
+  end
+end

data/lib/inkpen/extensions/table.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Table extension for TipTap.
+    #
+    # Enables table functionality including headers, cells, row/column
+    # operations, and cell merging. Uses ProseMirror's table system
+    # under the hood.
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::Table.new
+    #
+    # @example With custom options
+    #   extension = Inkpen::Extensions::Table.new(
+    #     resizable: true,
+    #     header_row: true,
+    #     cell_min_width: 100
+    #   )
+    #
+    # @see https://tiptap.dev/docs/examples/basics/tables
+    # @author Inkpen Team
+    # @since 0.2.0
+    #
+    class Table < Base
+      ##
+      # Default minimum cell width in pixels.
+      DEFAULT_CELL_MIN_WIDTH = 25
+
+      ##
+      # Default maximum cell width in pixels.
+      DEFAULT_CELL_MAX_WIDTH = 500
+
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :table
+      #
+      def name
+        :table
+      end
+
+      ##
+      # Whether table columns can be resized.
+      #
+      # @return [Boolean] true to enable column resizing
+      #
+      def resizable?
+        options.fetch(:resizable, true)
+      end
+
+      ##
+      # Whether the first row is treated as a header row.
+      #
+      # @return [Boolean] true if first row is header
+      #
+      def header_row?
+        options.fetch(:header_row, true)
+      end
+
+      ##
+      # Whether the first column is treated as a header column.
+      #
+      # @return [Boolean] true if first column is header
+      #
+      def header_column?
+        options.fetch(:header_column, false)
+      end
+
+      ##
+      # Minimum cell width in pixels.
+      #
+      # @return [Integer] minimum width
+      #
+      def cell_min_width
+        options.fetch(:cell_min_width, DEFAULT_CELL_MIN_WIDTH)
+      end
+
+      ##
+      # Maximum cell width in pixels (optional).
+      #
+      # @return [Integer, nil] maximum width or nil for unlimited
+      #
+      def cell_max_width
+        options[:cell_max_width]
+      end
+
+      ##
+      # Whether to show the table toolbar.
+      #
+      # @return [Boolean] true to show toolbar
+      #
+      def toolbar?
+        options.fetch(:toolbar, true)
+      end
+
+      ##
+      # Whether to allow cell background colors.
+      #
+      # @return [Boolean] true to enable cell backgrounds
+      #
+      def cell_backgrounds?
+        options.fetch(:cell_backgrounds, true)
+      end
+
+      ##
+      # Whether to allow cell merging.
+      #
+      # @return [Boolean] true to enable cell merging
+      #
+      def allow_merge?
+        options.fetch(:allow_merge, true)
+      end
+
+      ##
+      # Default number of rows when inserting a new table.
+      #
+      # @return [Integer] default row count
+      #
+      def default_rows
+        options.fetch(:default_rows, 3)
+      end
+
+      ##
+      # Default number of columns when inserting a new table.
+      #
+      # @return [Integer] default column count
+      #
+      def default_cols
+        options.fetch(:default_cols, 3)
+      end
+
+      ##
+      # Whether to include headers when inserting a new table.
+      #
+      # @return [Boolean] true to include header row
+      #
+      def with_header_row?
+        options.fetch(:with_header_row, true)
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        {
+          resizable: resizable?,
+          headerRow: header_row?,
+          headerColumn: header_column?,
+          cellMinWidth: cell_min_width,
+          cellMaxWidth: cell_max_width,
+          toolbar: toolbar?,
+          cellBackgrounds: cell_backgrounds?,
+          allowMerge: allow_merge?,
+          defaultRows: default_rows,
+          defaultCols: default_cols,
+          withHeaderRow: with_header_row?
+        }.compact
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          resizable: true,
+          header_row: true,
+          header_column: false,
+          cell_min_width: DEFAULT_CELL_MIN_WIDTH,
+          toolbar: true,
+          cell_backgrounds: true,
+          allow_merge: true,
+          default_rows: 3,
+          default_cols: 3,
+          with_header_row: true
+        )
+      end
+    end
+  end
+end