tiptap-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2347235752700026d263aa5a0616d89f99014c42da52edbf92c30374eb2cfded
+  data.tar.gz: d97eefd5023412988280b6edf6741186f310452ab657a02c62419296de680334
+SHA512:
+  metadata.gz: 79f61b79665a0a0d48cc69322c50b24d05a3b330c6f2a6dd8242f31dc628d8f9e1d69db06024b7bb642290c44a001df13379fcc45872a6c0f0f3e28df0bc4a3f
+  data.tar.gz: 4b5ab21878bccf69ccdc8dfdc3fe04bbc5e3a91a65140b6d2b1759bce3ed13a6169fb47d2697415cd5d27261fa27c11f1d40c2e0387a1f0e30cf38fc296244a0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-10-28
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Chad Wilken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# Tiptap
+
+A gem for parsing, generating, and rendering TipTap Documents and Nodes using Ruby.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add tiptap-ruby
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install tiptap-ruby
+
+## Usage
+
+### Parsing a TipTap Document
+
+You can parse a TipTap Document so that you can interact with it to do things such as add content (Nodes) or render it as HTML, JSON, or plain text:
+
+```ruby
+document = TipTap::Document.from_json(tiptap_json)
+```
+
+### Generate a New Document
+
+```ruby
+document = TipTap::Document.new
+```
+
+You can also pass a block and the new Document will be yielded to the block.
+
+```ruby
+TipTap::Document.new do |document|
+  # Do something with document
+end
+```
+
+### Add Content to the Document
+
+Now that you have a Document you can add content to it.
+
+```ruby
+document.heading(level: 1) do |heading|
+  heading.text("My Import Document", marks: [{type: "italic"}])
+end
+```
+
+Until the gem implements all of the node types and the documentation is complete, refer to the `Document` class to see the nodes that can be appended.
+
+### Generate Output
+
+Once you have a Document with some content you can render it to HTML, JSON, and plain text.
+
+#### JSON
+
+```ruby
+document.to_json # => { type: 'doc', content: […nodes]}
+```
+
+### HTML
+
+```ruby
+document.to_html # => <div class="tiptap-document"><h1><em>My Important Document</em></h1></div>
+```
+
+### Plain Text
+
+Rendering to plain text is useful if you want to search the contents of your TipTap content.
+
+```ruby
+document.to_plain_text # => My Important Document
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle install`.
+
+To release a new version, update the version number in `version.rb`, and then run `bin/release` or `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/chadwilken/tiptap-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/tip_tap/document.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "tip_tap/html_renderable"
+require "tip_tap/json_renderable"
+require "tip_tap/plain_text_renderable"
+require "tip_tap/has_content"
+
+# This is the class that all child nodes will be added to.
+# This is the root object for TipTap.
+module TipTap
+  class Document
+    include JsonRenderable
+    include HtmlRenderable
+    include PlainTextRenderable
+    include HasContent
+
+    self.type_name = "doc"
+    self.html_tag = :div
+    self.html_class_name = "tiptap-document"
+
+    def heading(level: 1, &block)
+      raise ArgumentError, "Block required" if block.nil?
+
+      add_content(Nodes::Heading.new(level: level, &block))
+    end
+
+    def paragraph(&block)
+      add_content(Nodes::Paragraph.new(&block))
+    end
+
+    def task_list(&block)
+      raise ArgumentError, "Block required" if block.nil?
+
+      add_content(Nodes::TaskList.new(&block))
+    end
+
+    def bullet_list(&block)
+      raise ArgumentError, "Block required" if block.nil?
+
+      add_content(Nodes::BulletList.new(&block))
+    end
+
+    def image(src:)
+      add_content(Nodes::Image.new(src: src))
+    end
+  end
+end

data/lib/tip_tap/has_content.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash"
+
+module TipTap
+  module HasContent
+    attr_reader :attrs, :content
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Create a new document or node, optionally passing in attributes (attrs) and nodes
+    # @param nodes [Array] An array of nodes to add to this node
+    # @param attributes [Hash] A hash of attributes to add to this node e.g. { 'level' => 1 }
+    def initialize(content = [], **attributes)
+      # This will convert the attrs key to camelcase for example :image_id is converted into 'imageId'
+      @attrs = Hash(attributes).deep_transform_keys { |key| key.to_s.camelcase(:lower) }
+      @content = content
+      yield self if block_given?
+    end
+
+    def find_node(node_type)
+      content.find { |child| child.is_a?(node_type) }
+    end
+
+    def add_content(node)
+      @content << node
+    end
+
+    module ClassMethods
+      # Create a new instance from a TipTap JSON object.
+      # All nodes are recursively parsed and converted to Ruby objects
+      # All nodes must be registered in the registry.
+      # @param json [Hash] The JSON object to parse
+      def from_json(json)
+        return new if json.nil?
+
+        json.deep_stringify_keys!
+
+        content = Array(json["content"]).map do |node|
+          TipTap.node_for(node["type"]).from_json(node)
+        end
+
+        new(content, **Hash(json["attrs"]))
+      end
+    end
+  end
+end

data/lib/tip_tap/html_renderable.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "action_view"
+
+module TipTap
+  module HtmlRenderable
+    include ActionView::Helpers::TextHelper
+    include ActionView::Helpers::AssetTagHelper
+
+    # ActionView::Helpers::TagHelper requires output_buffer accessor
+    # This is included by ActionView::Helpers::TextHelper
+    attr_accessor :output_buffer
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def html_tag=(name_or_proc)
+        @html_tag = name_or_proc
+      end
+
+      def html_tag
+        @html_tag
+      end
+
+      def html_class_name=(name_or_proc)
+        @html_class_name = name_or_proc
+      end
+
+      def html_class_name
+        @html_class_name
+      end
+    end
+
+    def html_tag
+      tag = self.class.html_tag
+      case tag
+      when Proc
+        instance_eval(&tag)
+      else
+        tag
+      end
+    end
+
+    def html_class_name
+      classes = self.class.html_class_name
+      case classes
+      when Proc
+        instance_eval(&classes)
+      else
+        classes
+      end
+    end
+
+    def to_html
+      content_tag(html_tag, safe_join(content.map(&:to_html)), class: html_class_name)
+    end
+  end
+end

data/lib/tip_tap/json_renderable.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "tip_tap/registry"
+
+module TipTap
+  module JsonRenderable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def type_name=(type_name)
+        @type_name = type_name
+        Registry.register(type_name, self)
+      end
+
+      def type_name
+        @type_name
+      end
+    end
+
+    def type_name
+      self.class.type_name
+    end
+
+    def include_empty_content_in_json?
+      true
+    end
+
+    # Generate a JSON object that is useable by the editor
+    def to_json
+      json = {type: type_name}
+      json = json.merge(content: content.map(&:to_json)) if should_include_content?
+      json = json.merge(attrs: attrs.deep_symbolize_keys) if attrs.present?
+      json
+    end
+
+    private
+
+    def should_include_content?
+      content.present? || (content.empty? && include_empty_content_in_json?)
+    end
+  end
+end

data/lib/tip_tap/node.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "tip_tap/html_renderable"
+require "tip_tap/json_renderable"
+require "tip_tap/plain_text_renderable"
+require "tip_tap/has_content"
+
+# This is the base class for all TipTap nodes.
+# It provides some basic functionality that all nodes need such as
+# converting to HTML, JSON, and plain text
+module TipTap
+  class Node
+    include HtmlRenderable
+    include JsonRenderable
+    include PlainTextRenderable
+    include HasContent
+  end
+end

data/lib/tip_tap/nodes/bullet_list.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class BulletList < Node
+      self.type_name = "bulletList"
+      self.html_tag = :ul
+      self.html_class_name = "bullet-list"
+
+      def list_item(&block)
+        raise ArgumentError, "Block required" if block.nil?
+
+        add_content(ListItem.new(&block))
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/hard_break.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class HardBreak < Node
+      self.type_name = "hardBreak"
+
+      def include_empty_content_in_json?
+        false
+      end
+
+      def to_html
+        tag.br
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/heading.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class Heading < Node
+      self.type_name = "heading"
+      self.html_tag = proc { "h#{level}" }
+
+      def text(text, marks: [])
+        add_content(Text.new(text, marks: marks))
+      end
+
+      def level
+        attrs["level"]
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/horizontal_rule.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class HorizontalRule < Node
+      self.type_name = "horizontalRule"
+
+      def include_empty_content_in_json?
+        false
+      end
+
+      def to_html
+        tag.hr
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/image.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class Image < Node
+      self.type_name = "image"
+
+      def include_empty_content_in_json?
+        false
+      end
+
+      def to_html
+        image_tag(src)
+      end
+
+      def src
+        attrs["src"]
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/list_item.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class ListItem < Node
+      self.type_name = "listItem"
+      self.html_tag = :li
+      self.html_class_name = "list-item"
+
+      def paragraph(&block)
+        raise ArgumentError, "Block required" if block.nil?
+
+        add_content(Paragraph.new(&block))
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/ordered_list.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class OrderedList < Node
+      self.type_name = "orderedList"
+      self.html_tag = :ol
+      self.html_class_name = "ordered-list"
+
+      def list_item(&block)
+        raise ArgumentError, "Block required" if block.nil?
+
+        add_content(ListItem.new(&block))
+      end
+
+      def start
+        attrs["start"]
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/paragraph.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class Paragraph < Node
+      self.type_name = "paragraph"
+      self.html_tag = :p
+
+      def text(text, marks: [])
+        add_content(Text.new(text, marks: marks))
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/task_item.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class TaskItem < Node
+      self.type_name = "taskItem"
+      self.html_tag = :li
+      self.html_class_name = proc { class_names("task-item", {checked: checked?}) }
+
+      def paragraph(&block)
+        raise ArgumentError, "Block required" if block.nil?
+
+        add_content(Paragraph.new(&block))
+      end
+
+      def checked?
+        attrs["checked"]
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/task_list.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "tip_tap/node"
+
+module TipTap
+  module Nodes
+    class TaskList < Node
+      self.type_name = "taskList"
+      self.html_tag = :ul
+      self.html_class_name = "task-list"
+
+      def task_item(checked: false, &block)
+        raise ArgumentError, "Block required" if block.nil?
+
+        add_content(TaskItem.new(checked: checked, &block))
+      end
+    end
+  end
+end

data/lib/tip_tap/nodes/text.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "tip_tap/json_renderable"
+require "tip_tap/html_renderable"
+
+module TipTap
+  module Nodes
+    class Text
+      include JsonRenderable
+      include HtmlRenderable
+
+      attr_reader :text, :marks
+
+      self.type_name = "text"
+
+      def initialize(text, marks: [])
+        @text = text
+        @marks = marks.map(&:deep_stringify_keys)
+      end
+
+      def self.from_json(json)
+        json.deep_stringify_keys!
+
+        new(json["text"], marks: Array(json["marks"]))
+      end
+
+      def to_json
+        {type: type_name, text: text, marks: marks.map(&:deep_symbolize_keys)}.compact_blank
+      end
+
+      def to_html
+        value = text
+        value = content_tag(:u, value) if underline?
+        value = content_tag(:em, value) if italic?
+        value = content_tag(:strong, value) if bold?
+        value = content_tag(:a, value, href: link_href, target: link_target) if link?
+        value
+      end
+
+      def to_plain_text
+        text
+      end
+
+      def italic?
+        has_mark_with_type?("italic")
+      end
+
+      def bold?
+        has_mark_with_type?("bold")
+      end
+
+      def underline?
+        has_mark_with_type?("underline")
+      end
+
+      def link?
+        has_mark_with_type?("link")
+      end
+
+      def link_href
+        marks.find { |mark| mark["type"] == "link" }&.dig("attrs", "href")
+      end
+
+      def link_target
+        marks.find { |mark| mark["type"] == "link" }&.dig("attrs", "target")
+      end
+
+      private
+
+      def has_mark_with_type?(type)
+        marks.any? { |mark| mark["type"] == type }
+      end
+    end
+  end
+end

data/lib/tip_tap/plain_text_renderable.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TipTap
+  module PlainTextRenderable
+    # Useful for searching
+    def to_plain_text
+      content.map(&:to_plain_text).join(" ")
+    end
+  end
+end

data/lib/tip_tap/registry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# This is the registry for all the nodes that TipTap knows about.
+# It's a simple hash that maps TipTap JS node names to Ruby classes.
+# Registering a new node is as simple as:
+# TipTap::Registry.register('myNode', MyNode)
+module TipTap
+  class Registry
+    MissingNodeError = Class.new(StandardError)
+
+    def self.register(name, klass)
+      registry[name.to_s] = klass
+    end
+
+    def self.node_for(name)
+      registry.fetch(name.to_s) { raise MissingNodeError.new("Unknown node type: #{name}") }
+    end
+
+    def self.clear
+      @registry = {}
+    end
+
+    def self.registry
+      @registry ||= {}
+    end
+  end
+end

data/lib/tip_tap/version.rb

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

data/lib/tip_tap.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "tip_tap/version"
+require "tip_tap/registry"
+require "tip_tap/document"
+require "tip_tap/nodes/bullet_list"
+require "tip_tap/nodes/hard_break"
+require "tip_tap/nodes/heading"
+require "tip_tap/nodes/horizontal_rule"
+require "tip_tap/nodes/list_item"
+require "tip_tap/nodes/ordered_list"
+require "tip_tap/nodes/paragraph"
+require "tip_tap/nodes/task_item"
+require "tip_tap/nodes/task_list"
+require "tip_tap/nodes/text"
+require "tip_tap/nodes/image"
+
+module TipTap
+  class Error < StandardError; end
+
+  def self.node_for(name)
+    Registry.node_for(name)
+  end
+end

data/lib/tiptap.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "tip_tap"

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: tiptap-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chad Wilken
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: A gem for parsing, generating, and rendering TipTap Documents and Nodes
+  using Ruby.
+email:
+- chad.wilken@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/tip_tap.rb
+- lib/tip_tap/document.rb
+- lib/tip_tap/has_content.rb
+- lib/tip_tap/html_renderable.rb
+- lib/tip_tap/json_renderable.rb
+- lib/tip_tap/node.rb
+- lib/tip_tap/nodes/bullet_list.rb
+- lib/tip_tap/nodes/hard_break.rb
+- lib/tip_tap/nodes/heading.rb
+- lib/tip_tap/nodes/horizontal_rule.rb
+- lib/tip_tap/nodes/image.rb
+- lib/tip_tap/nodes/list_item.rb
+- lib/tip_tap/nodes/ordered_list.rb
+- lib/tip_tap/nodes/paragraph.rb
+- lib/tip_tap/nodes/task_item.rb
+- lib/tip_tap/nodes/task_list.rb
+- lib/tip_tap/nodes/text.rb
+- lib/tip_tap/plain_text_renderable.rb
+- lib/tip_tap/registry.rb
+- lib/tip_tap/version.rb
+- lib/tiptap.rb
+homepage: https://github.com/chadwilken/tiptap-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/chadwilken/tiptap-ruby
+  source_code_uri: https://github.com/chadwilken/tiptap-ruby
+  changelog_uri: https://github.com/chadwilken/tiptap-ruby/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Parse, generate and render TipTap documents in Ruby.
+test_files: []