inkpen 0.7.1

data/lib/inkpen/engine.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Inkpen
+  class Engine < ::Rails::Engine
+    isolate_namespace Inkpen
+
+    initializer "inkpen.assets" do |app|
+      # Add stylesheets to asset pipeline
+      app.config.assets.paths << root.join("app/assets/stylesheets")
+      app.config.assets.paths << root.join("app/assets/javascripts")
+    end
+
+    initializer "inkpen.importmap", before: "importmap" do |app|
+      # Hook into importmap if available
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+      end
+    end
+
+    initializer "inkpen.helpers" do |app|
+      app.config.to_prepare do
+        ActionView::Base.include Inkpen::EditorHelper
+      end
+    end
+
+    # Allow precompilation of inkpen assets
+    initializer "inkpen.precompile" do |app|
+      app.config.assets.precompile += %w[inkpen/editor.css]
+    end
+  end
+end

data/lib/inkpen/extensions/base.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Base class for all Inkpen TipTap extensions.
+    #
+    # Extensions follow the TipTap extension pattern and are configured
+    # through this Ruby PORO layer before being passed to the JavaScript
+    # TipTap editor.
+    #
+    # @abstract Subclass and override {#name} and {#to_config} to implement
+    #   a custom extension.
+    #
+    # @example Creating a custom extension
+    #   class MyExtension < Inkpen::Extensions::Base
+    #     def name
+    #       :my_extension
+    #     end
+    #
+    #     def to_config
+    #       { custom_option: true }
+    #     end
+    #   end
+    #
+    # @author Inkpen Team
+    # @since 0.2.0
+    #
+    class Base
+      ##
+      # @return [Hash] the options passed during initialization
+      attr_reader :options
+
+      ##
+      # Initialize a new extension with optional configuration.
+      #
+      # @param options [Hash] configuration options for the extension
+      # @option options [Boolean] :enabled whether the extension is enabled (default: true)
+      #
+      def initialize(**options)
+        @options = default_options.merge(options)
+      end
+
+      ##
+      # The unique name of the extension.
+      #
+      # @abstract Subclasses must override this method.
+      # @return [Symbol] the extension name
+      # @raise [NotImplementedError] if not overridden in subclass
+      #
+      def name
+        raise NotImplementedError, "#{self.class} must implement #name"
+      end
+
+      ##
+      # Whether this extension is currently enabled.
+      #
+      # @return [Boolean] true if enabled
+      #
+      def enabled?
+        options.fetch(:enabled, true)
+      end
+
+      ##
+      # Convert the extension configuration to a hash for JSON serialization.
+      #
+      # This hash is passed to the JavaScript TipTap extension.
+      #
+      # @return [Hash] configuration hash
+      #
+      def to_config
+        {}
+      end
+
+      ##
+      # Full configuration including name and enabled status.
+      #
+      # @return [Hash] complete extension configuration
+      #
+      def to_h
+        {
+          name: name,
+          enabled: enabled?,
+          config: to_config
+        }
+      end
+
+      ##
+      # JSON representation of the extension.
+      #
+      # @return [String] JSON string
+      #
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      private
+
+      ##
+      # Default options for this extension.
+      #
+      # @return [Hash] default options
+      #
+      def default_options
+        { enabled: true }
+      end
+    end
+  end
+end

data/lib/inkpen/extensions/code_block_syntax.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Code Block with Syntax Highlighting extension.
+    #
+    # Enhances the standard code block with syntax highlighting using
+    # lowlight (highlight.js). Supports multiple programming languages
+    # with automatic language detection.
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::CodeBlockSyntax.new
+    #
+    # @example With custom languages
+    #   extension = Inkpen::Extensions::CodeBlockSyntax.new(
+    #     languages: [:ruby, :javascript, :python, :sql],
+    #     default_language: :ruby
+    #   )
+    #
+    # @see https://tiptap.dev/docs/examples/advanced/syntax-highlighting
+    # @author Inkpen Team
+    # @since 0.2.0
+    #
+    class CodeBlockSyntax < Base
+      ##
+      # All available programming languages for syntax highlighting.
+      # These are loaded from highlight.js via lowlight.
+      AVAILABLE_LANGUAGES = %i[
+        javascript
+        typescript
+        ruby
+        python
+        css
+        xml
+        html
+        json
+        bash
+        shell
+        sql
+        markdown
+        yaml
+        go
+        rust
+        java
+        kotlin
+        swift
+        php
+        c
+        cpp
+        csharp
+        elixir
+        erlang
+        haskell
+        scala
+        r
+        matlab
+        dockerfile
+        nginx
+        apache
+        graphql
+      ].freeze
+
+      ##
+      # Default languages to load (for performance).
+      DEFAULT_LANGUAGES = %i[
+        javascript
+        typescript
+        ruby
+        python
+        css
+        xml
+        json
+        bash
+        sql
+        markdown
+      ].freeze
+
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :code_block_syntax
+      #
+      def name
+        :code_block_syntax
+      end
+
+      ##
+      # Languages to enable for syntax highlighting.
+      #
+      # Only these languages will be loaded from highlight.js to
+      # reduce bundle size.
+      #
+      # @return [Array<Symbol>] enabled language identifiers
+      #
+      def languages
+        options.fetch(:languages, DEFAULT_LANGUAGES)
+      end
+
+      ##
+      # Default language when none is specified.
+      #
+      # @return [Symbol, nil] default language or nil for auto-detect
+      #
+      def default_language
+        options[:default_language]
+      end
+
+      ##
+      # Whether to show line numbers in code blocks.
+      #
+      # @return [Boolean] true to show line numbers
+      #
+      def line_numbers?
+        options.fetch(:line_numbers, false)
+      end
+
+      ##
+      # Whether to show a language selector dropdown.
+      #
+      # @return [Boolean] true to show language selector
+      #
+      def show_language_selector?
+        options.fetch(:language_selector, true)
+      end
+
+      ##
+      # Whether to enable copy-to-clipboard button.
+      #
+      # @return [Boolean] true to show copy button
+      #
+      def copy_button?
+        options.fetch(:copy_button, true)
+      end
+
+      ##
+      # CSS theme for syntax highlighting.
+      #
+      # @return [String] theme name (e.g., "github", "monokai", "dracula")
+      #
+      def theme
+        options.fetch(:theme, "github")
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        {
+          languages: languages,
+          defaultLanguage: default_language,
+          lineNumbers: line_numbers?,
+          languageSelector: show_language_selector?,
+          copyButton: copy_button?,
+          theme: theme,
+          lowlight: {
+            languages: languages
+          }
+        }
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          languages: DEFAULT_LANGUAGES,
+          line_numbers: false,
+          language_selector: true,
+          copy_button: true,
+          theme: "github"
+        )
+      end
+    end
+  end
+end

data/lib/inkpen/extensions/document_section.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # DocumentSection extension for TipTap.
+    #
+    # Provides true content grouping with a semantic H2 title and collapsible
+    # content. Unlike the layout Section extension (which controls width/spacing),
+    # DocumentSection groups related blocks under a heading for document structure.
+    #
+    # Features:
+    # - Semantic H2 title (integrates with Table of Contents)
+    # - Collapsible content with left-gutter toggle
+    # - Nesting support (sections within sections, up to 3 levels)
+    # - Draggable as a group
+    # - Auto-generated IDs for deep linking
+    #
+    # @example Basic usage
+    #   extension = Inkpen::Extensions::DocumentSection.new
+    #
+    # @example With custom options
+    #   extension = Inkpen::Extensions::DocumentSection.new(
+    #     default_collapsed: false,
+    #     allow_nesting: true,
+    #     max_depth: 3,
+    #     show_controls: true
+    #   )
+    #
+    # @see https://tiptap.dev/docs/editor/api/nodes
+    # @author Inkpen Team
+    # @since 0.8.0
+    #
+    class DocumentSection < Base
+      ##
+      # Default maximum nesting depth for sections.
+      DEFAULT_MAX_DEPTH = 3
+
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :document_section
+      #
+      def name
+        :document_section
+      end
+
+      ##
+      # Default collapsed state for new sections.
+      #
+      # @return [Boolean] true if sections start collapsed
+      #
+      def default_collapsed
+        options.fetch(:default_collapsed, false)
+      end
+
+      ##
+      # Whether sections can be nested within each other.
+      #
+      # @return [Boolean] true to allow nesting
+      #
+      def allow_nesting?
+        options.fetch(:allow_nesting, true)
+      end
+
+      ##
+      # Maximum nesting depth for sections.
+      #
+      # @return [Integer] maximum depth allowed (1-3)
+      #
+      def max_depth
+        depth = options.fetch(:max_depth, DEFAULT_MAX_DEPTH)
+        [[depth, 1].max, 3].min # Clamp between 1 and 3
+      end
+
+      ##
+      # Whether to show the collapse toggle control.
+      #
+      # @return [Boolean] true to show controls
+      #
+      def show_controls?
+        options.fetch(:show_controls, true)
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        {
+          defaultCollapsed: default_collapsed,
+          allowNesting: allow_nesting?,
+          maxDepth: max_depth,
+          showControls: show_controls?
+        }
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          default_collapsed: false,
+          allow_nesting: true,
+          max_depth: DEFAULT_MAX_DEPTH,
+          show_controls: true
+        )
+      end
+    end
+  end
+end

data/lib/inkpen/extensions/forced_document.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Inkpen
+  module Extensions
+    ##
+    # Forced Document Structure extension.
+    #
+    # Enforces a specific document structure where the first element must be
+    # a title heading (H1), optionally followed by a subtitle heading (H2).
+    # This prevents users from deleting required headings and ensures
+    # consistent document structure similar to Medium, Notion, or Dropbox Paper.
+    #
+    # @example Basic usage (title only)
+    #   extension = Inkpen::Extensions::ForcedDocument.new
+    #
+    # @example With subtitle enabled
+    #   extension = Inkpen::Extensions::ForcedDocument.new(
+    #     subtitle: true,
+    #     title_placeholder: "Your title here...",
+    #     subtitle_placeholder: "Add a subtitle..."
+    #   )
+    #
+    # @example Custom heading levels
+    #   extension = Inkpen::Extensions::ForcedDocument.new(
+    #     title_level: 1,
+    #     subtitle_level: 2,
+    #     subtitle: true
+    #   )
+    #
+    # @see https://tiptap.dev/docs/examples/advanced/forced-content-structure
+    # @author Inkpen Team
+    # @since 0.2.0
+    #
+    class ForcedDocument < Base
+      ##
+      # Default heading level for the title (H1).
+      DEFAULT_TITLE_LEVEL = 1
+
+      ##
+      # Default heading level for the subtitle (H2).
+      DEFAULT_SUBTITLE_LEVEL = 2
+
+      ##
+      # Default placeholder text for the title heading.
+      DEFAULT_TITLE_PLACEHOLDER = "Untitled"
+
+      ##
+      # Default placeholder text for the subtitle heading.
+      DEFAULT_SUBTITLE_PLACEHOLDER = "Add a subtitle..."
+
+      ##
+      # The unique name of this extension.
+      #
+      # @return [Symbol] :forced_document
+      #
+      def name
+        :forced_document
+      end
+
+      ##
+      # The heading level for the title (first heading).
+      #
+      # @return [Integer] heading level (1-6), default 1
+      #
+      def title_level
+        options.fetch(:title_level, options.fetch(:heading_level, DEFAULT_TITLE_LEVEL))
+      end
+
+      ##
+      # The heading level for the subtitle (second heading).
+      #
+      # @return [Integer] heading level (1-6), default 2
+      #
+      def subtitle_level
+        options.fetch(:subtitle_level, DEFAULT_SUBTITLE_LEVEL)
+      end
+
+      ##
+      # Whether subtitle is enabled.
+      #
+      # @return [Boolean] true if subtitle heading should be enforced
+      #
+      def subtitle?
+        options.fetch(:subtitle, false)
+      end
+
+      ##
+      # Placeholder text shown in the title heading when empty.
+      #
+      # @return [String] placeholder text
+      #
+      def title_placeholder
+        options.fetch(:title_placeholder, options.fetch(:placeholder, DEFAULT_TITLE_PLACEHOLDER))
+      end
+
+      ##
+      # Placeholder text shown in the subtitle heading when empty.
+      #
+      # @return [String] placeholder text
+      #
+      def subtitle_placeholder
+        options.fetch(:subtitle_placeholder, DEFAULT_SUBTITLE_PLACEHOLDER)
+      end
+
+      ##
+      # Whether to allow the title heading to be deleted.
+      #
+      # @return [Boolean] false by default (title cannot be deleted)
+      #
+      def allow_title_deletion?
+        options.fetch(:allow_deletion, false)
+      end
+
+      ##
+      # Whether to allow the subtitle heading to be deleted.
+      #
+      # @return [Boolean] true by default (subtitle can be deleted/cleared)
+      #
+      def allow_subtitle_deletion?
+        options.fetch(:allow_subtitle_deletion, true)
+      end
+
+      ##
+      # Document structure schema.
+      #
+      # Defines the required structure:
+      # - Without subtitle: heading block*
+      # - With subtitle: heading heading? block*
+      #
+      # @return [String] ProseMirror content expression
+      #
+      def content_expression
+        if subtitle?
+          "heading heading? block*"
+        else
+          "heading block*"
+        end
+      end
+
+      ##
+      # Convert to configuration hash for JavaScript.
+      #
+      # @return [Hash] configuration for the TipTap extension
+      #
+      def to_config
+        config = {
+          titleLevel: title_level,
+          titlePlaceholder: title_placeholder,
+          allowDeletion: allow_title_deletion?,
+          contentExpression: content_expression,
+          subtitle: subtitle?
+        }
+
+        if subtitle?
+          config.merge!(
+            subtitleLevel: subtitle_level,
+            subtitlePlaceholder: subtitle_placeholder,
+            allowSubtitleDeletion: allow_subtitle_deletion?
+          )
+        end
+
+        # Legacy support for headingLevel
+        config[:headingLevel] = title_level
+
+        config
+      end
+
+      private
+
+      def default_options
+        super.merge(
+          title_level: DEFAULT_TITLE_LEVEL,
+          subtitle_level: DEFAULT_SUBTITLE_LEVEL,
+          title_placeholder: DEFAULT_TITLE_PLACEHOLDER,
+          subtitle_placeholder: DEFAULT_SUBTITLE_PLACEHOLDER,
+          subtitle: false,
+          allow_deletion: false,
+          allow_subtitle_deletion: true
+        )
+      end
+    end
+  end
+end