milkdown_engine 0.1.1

data/app/models/milkdown_engine/md_document.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module MilkdownEngine
+  class MdDocument < ApplicationRecord
+    ChecklistItem = Data.define(:text, :checked)
+    Heading       = Data.define(:level, :id, :text)
+
+    validates :content, presence: true
+
+    before_save :set_title_from_content, if: -> { title.blank? && content_changed? }
+
+    # ── JSON query helpers (PostgreSQL jsonb_path_query) ─────────────────
+
+    # Extract task-list items from the ProseMirror JSON stored in +content+.
+    #
+    # In Milkdown's ProseMirror output, task-list items are regular
+    # +list_item+ nodes whose +attrs.checked+ is +true+ or +false+
+    # (regular list items have +checked: null+).
+    #
+    # Returns an Array of ChecklistItem (text:, checked:).
+    def checklist_items
+      rows = exec_jsonb_query(<<~SQL.squish)
+        SELECT
+          (item #>> '{attrs,checked}')::boolean AS checked,
+          string_agg(text_node #>> '{text}', '' ORDER BY text_ord) AS item_text
+        FROM jsonb_path_query(
+          (SELECT content FROM milkdown_engine_md_documents WHERE id = :id),
+          'strict $.** ? (@.type == "list_item" && @.attrs.checked != null)'
+        ) WITH ORDINALITY AS items(item, item_ord),
+        jsonb_path_query(item, 'strict $.** ? (@.type == "text")') WITH ORDINALITY AS texts(text_node, text_ord)
+        GROUP BY items.item_ord, item #>> '{attrs,checked}'
+        ORDER BY items.item_ord
+      SQL
+
+      rows.map { |row| ChecklistItem.new(text: row["item_text"], checked: row["checked"]) }
+    end
+
+    # Extract every heading from the document.
+    #
+    # Returns an Array of Heading (level:, id:, text:) in document order.
+    # Useful for building a table of contents.
+    def headings
+      rows = exec_jsonb_query(<<~SQL.squish)
+        SELECT
+          (heading #>> '{attrs,level}')::integer AS level,
+          heading #>> '{attrs,id}'                AS id,
+          string_agg(text_node #>> '{text}', '' ORDER BY text_ord) AS heading_text
+        FROM jsonb_path_query(
+          (SELECT content FROM milkdown_engine_md_documents WHERE id = :id),
+          'strict $.** ? (@.type == "heading")'
+        ) WITH ORDINALITY AS headings(heading, heading_ord),
+        jsonb_path_query(heading, 'strict $.** ? (@.type == "text")') WITH ORDINALITY AS texts(text_node, text_ord)
+        GROUP BY headings.heading_ord, heading #>> '{attrs,level}', heading #>> '{attrs,id}'
+        ORDER BY headings.heading_ord
+      SQL
+
+      rows.map { |row| Heading.new(level: row["level"], id: row["id"], text: row["heading_text"]) }
+    end
+
+    alias_method :table_of_contents, :headings
+
+    private
+
+    # Execute a raw SQL string that contains jsonb_path_query expressions.
+    #
+    # We avoid +sanitize_sql_array+ here because its +?+ placeholder syntax
+    # conflicts with the +?+ filter operator in PostgreSQL jsonb path
+    # expressions (e.g. '$.** ? (@.type == "heading")').
+    #
+    # Instead we interpolate the quoted id via +:id+ and +connection.quote+.
+    def exec_jsonb_query(sql)
+      quoted = sql.gsub(":id", self.class.connection.quote(id))
+      self.class.connection.select_all(quoted)
+    end
+
+    # Walk the ProseMirror JSON tree in Ruby to find the first heading's text.
+    # Runs before save so it doesn't require a DB round-trip.
+    def set_title_from_content
+      return unless content.is_a?(Hash)
+
+      heading = first_node_of_type(content, "heading")
+      return unless heading
+
+      self.title = collect_text(heading).presence
+    end
+
+    def first_node_of_type(node, type)
+      return node if node["type"] == type
+
+      Array(node["content"]).each do |child|
+        found = first_node_of_type(child, type)
+        return found if found
+      end
+
+      nil
+    end
+
+    def collect_text(node)
+      return node["text"].to_s if node["type"] == "text"
+
+      Array(node["content"]).map { |child| collect_text(child) }.join
+    end
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Vendored Milkdown bundle (built by esbuild from src/)
+pin "milkdown_engine/milkdown", to: "milkdown_engine/milkdown.min.js"
+
+# MilkdownEngine Stimulus controllers
+pin_all_from MilkdownEngine::Engine.root.join("app/javascript/milkdown_engine/controllers"),
+  under: "controllers/milkdown_engine", to: "milkdown_engine/controllers"

data/config/routes.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+MilkdownEngine::Engine.routes.draw do
+end

data/db/migrate/20260325000000_create_milkdown_engine_md_documents.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateMilkdownEngineMdDocuments < ActiveRecord::Migration[8.1]
+  def change
+    create_table :milkdown_engine_md_documents do |t|
+      t.string :title
+      t.jsonb :content, null: false,
+        default: { type: "doc", content: [{ type: "paragraph" }] }
+      t.timestamps
+    end
+
+    add_index :milkdown_engine_md_documents, :content,
+      using: :gin, opclass: :jsonb_path_ops,
+      name: "idx_md_documents_content_path"
+  end
+end

data/lib/milkdown_engine/engine.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "ui"
+
+module MilkdownEngine
+  class Engine < ::Rails::Engine
+    isolate_namespace MilkdownEngine
+
+    # Register importmap pins for Stimulus controllers
+    initializer "milkdown_engine.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << Engine.root.join("app/javascript")
+      end
+    end
+
+    # Add engine assets to the asset load path (for propshaft/sprockets)
+    initializer "milkdown_engine.assets" do |app|
+      app.config.assets.paths << Engine.root.join("app/assets/javascripts")
+      app.config.assets.paths << Engine.root.join("app/assets/stylesheets")
+
+      # Stimulus controllers live under app/javascript/ — add it so
+      # importmap pin_all_from URLs resolve through the asset pipeline.
+      app.config.assets.paths << Engine.root.join("app/javascript")
+
+      # rails-active-ui ships stylesheets.css directly in app/assets/
+      app.config.assets.paths << Ui::Engine.root.join("app/assets")
+    end
+
+    # Append engine migrations so host apps pick them up without copying
+    initializer "milkdown_engine.migrations", after: :load_config_initializers do |app|
+      unless app.root.to_s == root.to_s
+        engine_migrate_path = root.join("db/migrate").to_s
+        app.config.paths["db/migrate"] << engine_migrate_path
+        ActiveRecord::Migrator.migrations_paths << engine_migrate_path
+      end
+    end
+
+    # Make engine helpers available in host app views
+    initializer "milkdown_engine.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include MilkdownEngine::ApplicationHelper
+      end
+    end
+  end
+end

data/lib/milkdown_engine/version.rb

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

data/lib/milkdown_engine/version.rb.erb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MilkdownEngine
+  VERSION = "<%= version %>"
+end

data/lib/milkdown_engine.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "milkdown_engine/version"
+require "milkdown_engine/engine"
+
+module MilkdownEngine
+end

metadata

@@ -0,0 +1,175 @@
+--- !ruby/object:Gem::Specification
+name: milkdown_engine
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Nathan Kidd
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: stimulus-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails-active-ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides a Milkdown-based rich markdown editor as a Rails engine with
+  Stimulus controllers, importmap integration, and rails-active-ui components.
+email:
+- nathankidd@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/milkdown_engine/milkdown.min.js
+- app/assets/stylesheets/milkdown_engine/application.css
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_AMS-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_AMS-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_AMS-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Caligraphic-Bold.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Caligraphic-Bold.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Caligraphic-Bold.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Caligraphic-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Caligraphic-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Caligraphic-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Fraktur-Bold.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Fraktur-Bold.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Fraktur-Bold.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Fraktur-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Fraktur-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Fraktur-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Bold.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Bold.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Bold.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-BoldItalic.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-BoldItalic.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-BoldItalic.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Italic.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Italic.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Italic.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Main-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Math-BoldItalic.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Math-BoldItalic.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Math-BoldItalic.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Math-Italic.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Math-Italic.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Math-Italic.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Bold.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Bold.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Bold.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Italic.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Italic.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Italic.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_SansSerif-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Script-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Script-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Script-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size1-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size1-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size1-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size2-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size2-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size2-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size3-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size3-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size3-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size4-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size4-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Size4-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Typewriter-Regular.ttf
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Typewriter-Regular.woff
+- app/assets/stylesheets/milkdown_engine/fonts/KaTeX_Typewriter-Regular.woff2
+- app/assets/stylesheets/milkdown_engine/milkdown.css
+- app/controllers/milkdown_engine/application_controller.rb
+- app/helpers/milkdown_engine/application_helper.rb
+- app/javascript/milkdown_engine/controllers/editor_controller.js
+- app/models/milkdown_engine/application_record.rb
+- app/models/milkdown_engine/md_document.rb
+- config/importmap.rb
+- config/routes.rb
+- db/migrate/20260325000000_create_milkdown_engine_md_documents.rb
+- lib/milkdown_engine.rb
+- lib/milkdown_engine/engine.rb
+- lib/milkdown_engine/version.rb
+- lib/milkdown_engine/version.rb.erb
+homepage: https://github.com/n-at-han-k/milkdown-engine
+licenses:
+- Apache-2.0
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Rails engine for Milkdown markdown editing
+test_files: []