portable_text 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86981539153c16fb832e1221ed7d068fbb7fe986f807963c78cc0091f1921970
+  data.tar.gz: 65547bf22449bc8318e89f5cc462bed3a8bd48f490913aebeaece3a14fcac329
+SHA512:
+  metadata.gz: d04924353a52afe867c49c270cb9c5ed86b1313ac106a4b25200f03e7c87452d30212fa9d2e6da531a2dc7834f6ada62df69d2a40e91ad62824ff9e8ddd9e91f
+  data.tar.gz: 7d41d5138c9d7b830e7d2d9af3d7ad391a0de562b00c1df62d8d04031c1742df5e650f1d8ba2d21f16e50705506c029adec5f83502d37db51d2316cc83833e20

data/.rubocop.yml

@@ -0,0 +1,28 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,85 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2024-04-11 12:20:23 UTC using RuboCop version 1.63.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, EnforcedStyleForExponentOperator, EnforcedStyleForRationalLiterals.
+# SupportedStylesForExponentOperator: space, no_space
+# SupportedStylesForRationalLiterals: space, no_space
+Layout/SpaceAroundOperators:
+  Exclude:
+    - 'portable_text.gemspec'
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 21
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 13
+
+# Offense count: 14
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/portable_text.rb'
+    - 'lib/portable_text/block_types/base.rb'
+    - 'lib/portable_text/block_types/list.rb'
+    - 'lib/portable_text/block_types/span.rb'
+    - 'lib/portable_text/config.rb'
+    - 'lib/portable_text/errors/unimpleted_error.rb'
+    - 'lib/portable_text/html/configured.rb'
+    - 'lib/portable_text/html/content/image.rb'
+    - 'lib/portable_text/html/content/list.rb'
+    - 'lib/portable_text/html/mark_def/base.rb'
+    - 'lib/portable_text/html/serializer.rb'
+    - 'lib/portable_text/mark_defs/base.rb'
+    - 'lib/portable_text/mark_defs/link.rb'
+    - 'lib/portable_text/renderer.rb'
+
+# Offense count: 15
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: always, always_true, never
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - 'lib/portable_text/block_types/base.rb'
+    - 'lib/portable_text/block_types/block.rb'
+    - 'lib/portable_text/block_types/image.rb'
+    - 'lib/portable_text/block_types/list.rb'
+    - 'lib/portable_text/block_types/span.rb'
+    - 'lib/portable_text/config.rb'
+    - 'lib/portable_text/errors/unimpleted_error.rb'
+    - 'lib/portable_text/html/configured.rb'
+    - 'lib/portable_text/html/content/image.rb'
+    - 'lib/portable_text/html/content/list.rb'
+    - 'lib/portable_text/html/mark_def/base.rb'
+    - 'lib/portable_text/html/serializer.rb'
+    - 'lib/portable_text/mark_defs/base.rb'
+    - 'lib/portable_text/mark_defs/link.rb'
+    - 'lib/portable_text/renderer.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'lib/portable_text/block_types/list.rb'
+    - 'lib/portable_text/html/content/image.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 126

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Maxime Souillat
+
+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,357 @@
+# Ruby Portable Text
+
+A ruby library to render [Portable text](https://www.sanity.io/docs/presenting-block-text)
+
+
+This gem is meant to be easy to use but is also highly configurable and extensible to match many use cases. By default, it can serialize Portable Text to HTML.
+
+You can:
+
+- easily render default PortableText blocks in html without any configuration
+- create custom block types, mark_defs. Add them or replace existing ones.
+- create custom HTML serializers for each block type or mark def. Add them or replace existing ones.
+- customize each HTML node with custom attributes
+- create a new serializer
+
+This is a very early release so please open issues if something doesn't work as intended.
+
+
+## Installation
+
+```other
+gem install portable_text
+```
+
+
+
+## Usage
+
+See [Rails usage](#rails-usage) for usage in rails
+
+`PortableText::Serializer` takes 2 parameters:
+
+- `content:`  , the portable text Array
+- `to:` , the rendering format. It defaults to: `:html`
+
+> You can also use the `:plain` rendering format to show the text without any formatting. The plain serializer is very basic and does not support any configuration, but it can be used as a starting point to create a new serializer.
+
+PortableText accepts 2 methods, `render` and `convert!`.
+  - `render` renders the content to the specified format defined in the `to` parameter. See [How to render html ?](#how-to-render-html) for more information.
+  - `convert!` converts the content to be used by the library. 
+    - It is useful for debugging purposes.
+    - It transforms the keys to ruby format.
+    - It creates the block types and mark definitions as objects, along with their children and marks, and creates a new data structure for list items.
+
+### How to render html?
+
+Under the hood, the html renderer uses [Phlex](https://www.phlex.fun), a templating language which allows to create html in plain ruby.
+
+```ruby
+content = [
+  {
+      "_key": "12345ffxx",
+      "_type": "block",
+      "children": [{ 
+        "_key": "78910xxyy", 
+        "_type": "span", 
+        "marks": [],
+        "text": "Hello world!" 
+      }],
+      "markDefs": [],
+      "style": "h1"
+    }
+]
+
+portable_text = PortableText::Serializer.new(content: content, to: :html)
+
+# Since the HTML renderer uses Phlex, you can either include the rendering module 
+# and use the render method...
+include PortableText::Html::Rendering
+render portable_text.render
+# => <h1>Hello world!</h1>
+
+# ... Or you can directly call the Phlex template
+portable_text.render.call
+# => <h1>Hello world!</h1>
+```
+
+
+### Rails usage
+
+To use the `PortableText` HTML serializer in rails, you need to add `phlex-rails` to the Gemfile.
+
+You don’t need to do the whole phlex installation (as described in the Phlex documentation) if you don’t intend to use Phlex to replace your usual templating language.
+
+```ruby
+gem 'portable_text'
+gem 'phlex-rails'
+```
+
+Then run `bundle install`
+
+Then, in a controller or a view, just use `render` as usual.
+
+```ruby
+portable_text = PortableText::Serializer.new(content: content, to: :html)
+render portable_text.render
+```
+
+
+
+## Configuration
+
+This library is highly  customizable through configuration. This is very straightforward as configuration is just a bunch of hashes that either define classes or key-value pairs.
+
+Since this library is meant to be used for multiple use cases, and possibly several serializers at once, the type definitions are independent from the rendering.
+
+So, in order to use a block type or a mark definition, one has to:
+
+- register it in the PortableText configuration, so it can be passed as an object to the serializer
+- create the template in the serializer (see HTML configuration)
+
+
+
+### Registering block types
+
+```ruby
+content = [
+  { 
+    "_key": "12345ffxx", 
+    "_type": "myType", 
+    ...,
+    "url": "https://www.github.com",
+    "image_url": "https://www.myimage.com/my_image.jpg",
+    "children": [{ 
+        "_key": "78910xxyy", 
+        "_type": "span", 
+        "marks": [],
+        "text": "Github" 
+      }]
+  }
+]
+
+# Under the hood, this library uses dry-initializer.
+# You can use the option method to configure it easily
+class MyBlock < PortableText::BlockTypes::Base
+  option :url, default: proc { "" }
+  option :image_url, default: proc { "" }
+  # children is an inherited option so it does not need to be added here
+end
+
+# Or use plain old ruby. It needs to have attr_readers!
+class MyBlock < PortableText::BlockTypes::Base
+  attr_reader :url, :image_url
+  
+  def initialize(url: "", image_url:, **)
+    super
+    @url = url
+    @image_url = image_url
+  end
+end
+
+# PortableText transforms keys to ruby format so use conventional ruby!
+# myType becomes my_type.
+PortableText.config.block.types.merge! { my_block: MyBlock }
+```
+
+
+#### Default block types
+
+It’s probably a good idea to leave the `list` block type untouched. Change at your own risk.
+
+```ruby
+{ 
+  block: BlockTypes::Block,
+  image: BlockTypes::Image,
+  list: BlockTypes::List,
+  span: BlockTypes::Span
+}
+```
+
+
+### Registering mark definitions
+
+It’s very similar to registering blocks. In case of doubt, refer to the block documentation.
+
+```ruby
+content = [
+  { 
+    "_key": "12345ffxx", 
+    "_type": "block", 
+    ...,
+    "markDefs": [{ "_key" => "456", "_type" => "newMarkDef" }],
+  }
+]
+
+class NewMarkDef < PortableText::MarkDefs::Base
+  option :label, default: proc { "" }
+end
+
+PortableText.config.block.mark_defs.merge! { new_mark_def: NewMarkDef }
+```
+
+
+
+## Html Serializer configuration
+
+After registering your block type or mark definition, you need to create its template.
+
+Each template takes one argument, a block.
+
+
+### Block Type Template
+
+```ruby
+# Let's use the block defined earlier in Registering block types
+
+class Html::MyBlock < PortableText::Html::BaseComponent
+  # You can include PortableText::Html::Configured 
+  # to get access to the html serializer configuration helpers
+  # The #config method allows you to access config values  
+  # The #block_type(:key) method is a shortcut to the relevant block_type
+  include PortableText::Html::Configured
+  
+  # This library uses dry-initializer 
+  # so you can use `param` to create a simple parameter
+  
+  # There is no attribute_reader so `param :my_block` generates `@my_block`
+  # This is recommended because some common HTML method names could conflict with
+  # Phlex methods, like `title`. 
+  param :my_block
+ 
+  def view_template
+    div do
+      img(src: @my_block.image_url)
+      link
+    end
+  end
+
+  private
+
+  def link
+    a(href: @my_block.url) do 
+      @my_block.children.each do |child|
+        render block_type(:span).new(child, mark_defs: nil)
+      end
+    end
+  end
+end
+
+# It needs to have the same key as the one registered before.
+PortableText::Html.config.block.types.merge! { my_block: Html::MyBlock }
+```
+
+
+### Mark Definition template
+
+Each mark definition takes one argument, a mark definition registered in the configuration.
+
+```ruby
+# Let's use the mark definition defined earlier in Registering mark definition
+
+class Html::NewMarkDef < PortableText::Html::BaseComponent
+  param :mark_def
+
+  # &block is mandatory because mark definitions always contain other nodes
+  def view_template(&block)
+    a(href: @mark_def.url) { block.call }
+  end
+end
+
+# It needs to have the same key as the one registered before.
+PortableText::Html.config.block.mark_defs.merge! { new_mark_def: Html::NewMarkDef }
+```
+
+
+### Customizing html nodes
+
+Every HTML node is customizable through config and looks this way:
+
+`h1: { node: :h1 }`
+
+You can add HTML attributes by appending them. For example:
+
+```ruby
+h1: { node: :h1, class: "header" }
+```
+
+
+### Configuring marks
+
+You can configure marks by updating the marks setting.
+
+```ruby
+PortableText::Html.config.span.marks.merge! { strong: { node: :b,  }}
+
+# Defaults
+{ 
+  strong: { node: :strong },
+  em: { node: :em }
+}
+```
+
+
+### Configuring styles
+
+```ruby
+PortableText::Html.config.block.styles.merge! { h1: { node: :h3, class: "header" }}
+
+
+# Defaults
+{
+  h1: { node: :h1 },
+  h2: { node: :h2 },
+  h3: { node: :h3 },
+  h4: { node: :h4 },
+  h5: { node: :h5 },
+  h6: { node: :h6 },
+  blockquote: { node: :blockquote },
+  normal: { node: :p },
+  li: { node: :li }
+}
+```
+
+
+### Configuring list types
+
+```ruby
+PortableText::Html.config.block.list_types.merge! { bullet: { node: :div }}
+
+# Defaults
+{
+  bullet: { node: :ul },
+  numeric: { node: :ol }
+}
+```
+
+
+### Adding a new serializer
+
+You can add a new serializer by creating a new class. You then need to add it the the config.
+
+The serializer needs to have a `content` method and takes a list of `blocks` as only parameter.
+
+```ruby
+class MySerializer
+  def initialize(blocks)
+    @blocks = blocks
+  end
+
+  def content(**options)
+    blocks.map |block|
+      block.type + " - " + block.key + " - " + options[:context]
+    end.join(" ")
+  end
+end
+
+PortableText.config.serializers.merge! { my_serializer: MySerializer }
+
+content = [{ "_key": "12345ffxx", "_type": "block", ... }]
+serializer = PortableText::Serializer.new(content: content, to: :my_serializer)
+
+# render forwards any keyword argument to the content method in the serializer
+serializer.render(context: "readme")
+# => block - 12345ffxx - readme
+```
+
+

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+require "rake/testtask"
+
+RuboCop::RakeTask.new
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task default: %i[test rubocop]

data/lib/portable_text/block_types/base.rb

@@ -0,0 +1,19 @@
+module PortableText
+  module BlockTypes
+    class Base
+      extend Dry::Initializer
+
+      option :_key, as: :key
+      option :_type, as: :type
+      option :markDefs, as: :mark_defs, default: proc { [] }
+      option :children, default: proc { [] }
+      option :style, optional: true
+      option :listItem, as: :list_item, optional: true
+      option :level, optional: true
+      option :asset, optional: true
+
+      def list? = false
+      def list_item? = list_item.present?
+    end
+  end
+end

data/lib/portable_text/block_types/block.rb

@@ -0,0 +1,6 @@
+module PortableText
+  module BlockTypes
+    class Block < Base
+    end
+  end
+end

data/lib/portable_text/block_types/image.rb

@@ -0,0 +1,6 @@
+module PortableText
+  module BlockTypes
+    class Image < Base
+    end
+  end
+end

data/lib/portable_text/block_types/list.rb

@@ -0,0 +1,64 @@
+# A list can contain blocks and child lists.
+# items: [Block, List, Block, List, Block]
+
+module PortableText
+  module BlockTypes
+    class List
+      extend Dry::Initializer
+
+      option :list_type, default: proc { 'bullet' }
+      option :items, default: proc { [] }
+      option :level, default: proc { 1 }
+      option :parent, default: proc { nil }
+
+      def list? = true
+      def type = "list"
+
+      # Adds a block to the list.
+      # If the block is on same level as the list, it will be added to the list.
+      # If the block is on a higher level, it will be added to a child list
+      # Else it will be added to the nearest ancestor list.
+      def add(block)
+        if block.level == level
+          items << block
+        elsif block.level > level
+          add_child(block)
+        else
+          ancestor = find_matching_ancestor(block)
+          ancestor.items << block
+        end
+      end
+
+      protected
+
+      def find_matching_ancestor(block)
+        return self if block.level == level
+
+        parent.find_matching_ancestor(block) if block.level != level
+      end
+
+      def add_child(block)
+        sub_list = find_sub_list(block, level)
+
+        if sub_list.present?
+          sub_list.add(block)
+        else
+          items << List.new(items: [block], level: block.level, parent: self)
+        end
+      end
+
+      def find_sub_list(block, current_level)
+        target = block.level - 1
+
+        sub_list = items.reverse.find do |item|
+          item.list? && item.level == current_level + 1
+        end
+
+        return unless sub_list
+        return sub_list if sub_list.level == target
+
+        sub_list.find_sub_list(block, current_level + 1)
+      end
+    end
+  end
+end

data/lib/portable_text/block_types/null.rb

@@ -0,0 +1,6 @@
+module PortableText
+  module BlockTypes
+    class Null < Base
+    end
+  end
+end

data/lib/portable_text/block_types/span.rb

@@ -0,0 +1,12 @@
+module PortableText
+  module BlockTypes
+    class Span
+      extend Dry::Initializer
+
+      option :marks, default: proc { [] }
+      option :_key, as: :key
+      option :_type, as: :type
+      option :text, default: proc { nil }
+    end
+  end
+end

data/lib/portable_text/config.rb

@@ -0,0 +1,27 @@
+module PortableText
+  class Config
+    extend Dry::Configurable
+
+    # Default settings
+    # These can be overridden
+    # Example: PortableText.config.block.types.merge!({ block: MyCustomBlock })
+
+    setting :block do
+      setting :types, default: {
+        block: BlockTypes::Block,
+        image: BlockTypes::Image,
+        list: BlockTypes::List,
+        span: BlockTypes::Span
+      }
+
+      setting :mark_defs, default: {
+        link: MarkDefs::Link
+      }
+    end
+
+    setting :serializers, default: {
+      html: Html::Serializer,
+      plain: Plain::Serializer
+    }
+  end
+end

data/lib/portable_text/errors/unimplemented_error.rb

@@ -0,0 +1,9 @@
+module PortableText
+  module Errors
+    class UnimplementedError < StandardError
+      def initialize(msg = "Please implement this method")
+        super
+      end
+    end
+  end
+end

data/lib/portable_text/errors/unknown_serializer_error.rb

@@ -0,0 +1,9 @@
+module PortableText
+  module Errors
+    class UnknownSerializerError < StandardError
+      def initialize(msg = "This serializer is not recognized by PortableText::Config.serializers")
+        super
+      end
+    end
+  end
+end