pressroom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4713e4ba3f3eaae896ab1ad8b152749fa9c0be2a66cf11210a57fd43ba5c2d7
+  data.tar.gz: cde078d6ebe1273874c9da4610b92866489f163e8b5fbeb4cd6feb1e58177640
+SHA512:
+  metadata.gz: f712eaa9e76b6ffa4bdab60c5fb14e09d2609872d4fdbe2dd5ab8e7e7f247684a4cee01a8de66b3771fbac532381fcf2750fbfde534954ecfc8bbff5d84e2986
+  data.tar.gz: 37524af128ab5f3d6f27516a41d51a1a5e52086396d3f3f169acf574f981364e20f191b8e0929803acdf0fcf43292d4b3e6c549f0c1ae129ecb069c2ed121d31

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Block registry: one Ruby description drives the editor, server-side
+  rendering, sanitization and search-text extraction.
+- Seven built-in blocks: paragraph, header, list (nested), quote, code,
+  image, delimiter.
+- Article model with drafts, archiving and schedule-free scheduled
+  publication.
+- Slugs that survive Cyrillic titles. Transliteration rules for :ru and
+  :uk ship with the gem and are applied automatically when the configured
+  locale has none, so a Russian title yields a real slug out of the box.
+- Hierarchical categories and flat tags, with no external gems.
+- Mountable admin that inherits the host controller and fails closed
+  without an authentication hook.
+- Editor.js, Stimulus and Turbo vendored and pinned through importmap; no
+  Node build required.
+- RSS 2.0 and Atom feeds.
+- Optional ActiveStorage-backed image uploads.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Alex Andreiev
+
+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,172 @@
+# Pressroom
+
+Block-based article publishing for Rails, as a mountable engine.
+
+Pressroom adds a block editor, an article model with drafts and scheduled
+publication, categories, tags and feeds to an application you already have.
+It brings no authentication, no user model and no public routes — those stay
+yours.
+
+Its distinguishing feature is the **block registry**: a block is described
+once in Ruby, and that single description drives the editor, server-side
+rendering, sanitization and search-text extraction.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "pressroom"
+```
+
+```bash
+bundle install
+bin/rails db:migrate
+```
+
+Mount the admin:
+
+```ruby
+# config/routes.rb
+mount Pressroom::Engine => "/admin"
+```
+
+## Configuration
+
+```ruby
+# config/initializers/pressroom.rb
+Pressroom.configure do |config|
+  # Required. Without it the admin refuses to open.
+  config.authenticate_with do
+    redirect_to main_app.root_path unless current_user&.editor?
+  end
+
+  config.author_class = "User"
+  config.transliteration_locale = :ru   # slug rules for :ru and :uk ship with the gem
+end
+```
+
+Pressroom **fails closed**: an admin with no `authenticate_with` hook raises
+rather than letting anyone in.
+
+## Rendering an article
+
+Pressroom does not own your public routes. Write your own controller and
+view, and render the document:
+
+```erb
+<h1><%= @post.title %></h1>
+<%= render_blocks @post %>
+```
+
+Optionally include the structural stylesheet. It contains no typography,
+colour or spacing — only the handful of rules without which a block is
+broken rather than merely unstyled:
+
+```erb
+<%= stylesheet_link_tag "pressroom/content" %>
+```
+
+## Registering your own block
+
+```ruby
+Pressroom.register_block :callout do |b|
+  b.tool "Callout"                     # the Editor.js tool class
+  b.schema do
+    string :title, required: true
+    html   :body                       # html fields are sanitized; string fields are escaped
+    enum   :tone, in: %w[info warning], default: "info"
+  end
+  b.partial "blocks/callout"
+  b.searchable { |data| data["title"] }
+end
+```
+
+Pin the JavaScript tool from your own importmap and it appears in the
+toolbar. Field types: `string`, `html`, `integer`, `boolean`, `enum`,
+`array`, `nested`, `tree`.
+
+## Publication
+
+Publication is a timestamp comparison, not a background job:
+
+```ruby
+post.update!(status: :published, published_at: Time.current)     # live now
+post.update!(status: :published, published_at: 3.days.from_now)  # scheduled
+
+Pressroom::Post.published   # status published AND published_at <= now
+```
+
+Nothing polls and nothing is enqueued. A scheduled post becomes visible the
+moment its timestamp passes. The admin exposes both as buttons: *Publish
+now*, *Unpublish*, and a *Schedule publication* field.
+
+## Feeds
+
+```ruby
+feed = Pressroom::Feed.new(
+  Pressroom::Post.published.recent.limit(20),
+  title: "Example blog",
+  url: "https://example.com",
+  description: "Latest posts"
+) { |post| post_url(post) }
+
+render xml: feed.to_rss   # or feed.to_atom
+```
+
+## Search
+
+Pressroom maintains a `plain_text` column on every save and does not search
+it. Index it with whatever you already use:
+
+```ruby
+Pressroom::Post.published.where("plain_text ILIKE ?", "%rails%")
+```
+
+## Images
+
+The image block renders from a URL always. File uploads additionally require
+ActiveStorage; when it is present the upload endpoint and the editor's image
+tool are enabled automatically. Uploads keep CSRF protection — the editor
+sends the token as a request header.
+
+## Built-in blocks
+
+`paragraph`, `header`, `list` (nested), `quote`, `code`, `image`,
+`delimiter`. Tables, checklists, embeds and attachments are deliberately not
+included — register them yourself.
+
+## JavaScript
+
+Editor.js, Stimulus and Turbo are vendored into the gem and pinned through
+importmap. No Node build step is required in your application, and nothing
+is fetched from a CDN, so a strict CSP and an offline network are both fine.
+
+Stimulus and Turbo are pinned under private names (`pressroom/stimulus`,
+`pressroom/turbo`) so they cannot collide with your own pins for those
+packages.
+
+## Security
+
+- Fields declared `html` are sanitized through an allow-list; every other
+  field is escaped by ERB.
+- The allow-list is configurable via `sanitizer_tags` and
+  `sanitizer_attributes`.
+- An unknown block type, malformed stored JSON, a missing partial or a
+  deleted author degrade to a logged skip in production and raise in
+  development, so one damaged article cannot take a page down.
+
+## Public API and versioning
+
+Semver applies to: `Pressroom.register_block` and its block DSL,
+`Pressroom.configure`, `Pressroom::Post`, `Pressroom::Category`,
+`Pressroom::Tag`, `Pressroom::Feed`, the `render_blocks` helper, and the
+stored JSON format. Everything else is internal.
+
+## Requirements
+
+Ruby >= 3.4, Rails >= 7.2. Tested against Rails 7.2, 8.0 and 8.1 on
+PostgreSQL and SQLite.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+Dir.glob("lib/tasks/*.rake").each { |task_file| load task_file }

data/app/assets/javascripts/pressroom/application.js

@@ -0,0 +1,18 @@
+import "pressroom/turbo"
+import { Application } from "pressroom/stimulus"
+import PressroomEditorController from "pressroom/controllers/editor_controller"
+
+// Turbo is loaded here on purpose. A host application almost certainly runs
+// Turbo Drive, so navigating into the admin caches these pages whether or not
+// this layout asks for it -- which means the editor's teardown really does
+// have to work. Loading it here makes the admin behave in tests the way it
+// behaves in production instead of hiding the problem.
+//
+// The admin runs its own Stimulus application rather than reusing the host's.
+// The admin layout is ours and loads only this module, so there is nothing to
+// share, and a self-contained instance means the gem never depends on how the
+// host names or boots its controllers.
+const application = Application.start()
+application.register("pressroom-editor", PressroomEditorController)
+
+export { application }

data/app/assets/javascripts/pressroom/controllers/editor_controller.js

@@ -0,0 +1,146 @@
+import { Controller } from "pressroom/stimulus"
+import EditorJS from "@editorjs/editorjs"
+import Header from "@editorjs/header"
+import List from "@editorjs/list"
+import Quote from "@editorjs/quote"
+import CodeTool from "@editorjs/code"
+import ImageTool from "@editorjs/image"
+import Delimiter from "@editorjs/delimiter"
+import Marker from "@editorjs/marker"
+import InlineCode from "@editorjs/inline-code"
+
+export default class extends Controller {
+  static targets = ["field", "holder"]
+  static values = { uploadUrl: String }
+
+  connect() {
+    this.beforeCache = this.beforeCache.bind(this)
+    this.onSubmitClick = this.onSubmitClick.bind(this)
+    this.flushing = false
+
+    this.editor = new EditorJS({
+      holder: this.holderTarget,
+      data: this.readDocument(),
+      tools: this.tools(),
+      // The hidden field is kept current as the author types rather than
+      // serialized when the form is submitted. Intercepting submit would
+      // mean preventDefault, an await, and then re-submitting -- and a
+      // nested requestSubmit() raised from inside a submit event is
+      // silently ignored by the browser. Keeping the field fresh leaves
+      // form submission entirely to Turbo, with nothing to re-enter.
+      onChange: () => this.persist()
+    })
+
+    document.addEventListener("turbo:before-cache", this.beforeCache)
+    this.form?.addEventListener("click", this.onSubmitClick, true)
+  }
+
+  disconnect() {
+    document.removeEventListener("turbo:before-cache", this.beforeCache)
+    this.form?.removeEventListener("click", this.onSubmitClick, true)
+    this.teardown()
+  }
+
+  get form() {
+    return this.element.closest("form")
+  }
+
+  csrfToken() {
+    return document.querySelector('meta[name="csrf-token"]')?.content || ""
+  }
+
+  // Flush the editor before the form is submitted.
+  //
+  // This hooks the submit button's click rather than the form's submit
+  // event on purpose. Serializing is asynchronous, so the handler must
+  // stop the default action, await, and then let it happen again -- and a
+  // requestSubmit() raised from inside a submit event is silently dropped
+  // by the browser. Re-dispatching a click is not, so Turbo still handles
+  // the submission normally.
+  //
+  // Editor.js debounces onChange, so relying on that alone would lose the
+  // last thing an author typed before hitting save.
+  async onSubmitClick(event) {
+    if (this.flushing) return
+
+    const submitter = event.target.closest?.("input[type=submit], button[type=submit]")
+    if (!submitter) return
+
+    event.preventDefault()
+    event.stopPropagation()
+
+    this.flushing = true
+    await this.persist()
+    submitter.click()
+    this.flushing = false
+  }
+
+  readDocument() {
+    try {
+      const parsed = JSON.parse(this.fieldTarget.value || "{}")
+      return { blocks: parsed.blocks || [] }
+    } catch {
+      return { blocks: [] }
+    }
+  }
+
+  tools() {
+    const tools = {
+      header: Header,
+      list: List,
+      quote: Quote,
+      code: CodeTool,
+      delimiter: Delimiter,
+      marker: Marker,
+      inlineCode: InlineCode
+    }
+
+    // The image tool is only useful when the host exposes an upload
+    // endpoint, which it does only when ActiveStorage is available.
+    if (this.hasUploadUrlValue && this.uploadUrlValue) {
+      tools.image = {
+        class: ImageTool,
+        config: {
+          endpoints: { byFile: this.uploadUrlValue },
+          // Editor.js posts FormData without a Rails CSRF token, so it is
+          // supplied as a header instead of disabling CSRF protection.
+          additionalRequestHeaders: { "X-CSRF-Token": this.csrfToken() }
+        }
+      }
+    }
+
+    return tools
+  }
+
+  async persist() {
+    if (!this.editor) return
+
+    try {
+      const output = await this.editor.save()
+      this.fieldTarget.value = JSON.stringify(output)
+    } catch (error) {
+      console.error("pressroom: could not serialize the editor", error)
+    }
+  }
+
+  // Turbo caches a snapshot of the page on navigation. A live editor left
+  // in that snapshot is restored as markup and then initialized a second
+  // time, producing two editors and duplicated content.
+  beforeCache() {
+    this.teardown()
+    this.holderTarget.innerHTML = ""
+  }
+
+  teardown() {
+    const editor = this.editor
+    if (!editor) return
+
+    this.editor = null
+
+    try {
+      editor.destroy()
+    } catch {
+      // The editor may not have finished initializing; nothing to clean up.
+    }
+  }
+}

data/app/assets/javascripts/pressroom/vendor/code.js

@@ -0,0 +1,181 @@
+(function(){"use strict";try{if(typeof document<"u"){var e=document.createElement("style");e.appendChild(document.createTextNode(".ce-code__textarea{min-height:200px;font-family:Menlo,Monaco,Consolas,Courier New,monospace;color:#41314e;line-height:1.6em;font-size:12px;background:#f8f7fa;border:1px solid #f1f1f4;box-shadow:none;white-space:pre;word-wrap:normal;overflow-x:auto;resize:vertical}")),document.head.appendChild(e)}}catch(o){console.error("vite-plugin-css-injected-by-js",o)}})();
+function c(l, t) {
+  let a = "";
+  for (; a !== `
+` && t > 0; )
+    t = t - 1, a = l.substr(t, 1);
+  return a === `
+` && (t += 1), t;
+}
+const h = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none" viewBox="0 0 24 24"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 8L5 12L9 16"/><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 8L19 12L15 16"/></svg>';
+/**
+ * CodeTool for Editor.js
+ * @version 2.0.0
+ * @license MIT
+ */
+class d {
+  /**
+   * Notify core that read-only mode is supported
+   * @returns true if read-only mode is supported
+   */
+  static get isReadOnlySupported() {
+    return !0;
+  }
+  /**
+   * Allows pressing Enter key to create line breaks inside the CodeTool textarea
+   * This enables multi-line input within the code editor.
+   * @returns true if line breaks are allowed in the textarea
+   */
+  static get enableLineBreaks() {
+    return !0;
+  }
+  /**
+   * Render plugin`s main Element and fill it with saved data
+   * @param options - tool constricting options
+   * @param options.data — previously saved plugin code
+   * @param options.config - user config for Tool
+   * @param options.api - Editor.js API
+   * @param options.readOnly - read only mode flag
+   */
+  constructor({ data: t, config: e, api: a, readOnly: s }) {
+    this.api = a, this.readOnly = s, this.placeholder = this.api.i18n.t(e.placeholder || d.DEFAULT_PLACEHOLDER), this.CSS = {
+      baseClass: this.api.styles.block,
+      input: this.api.styles.input,
+      wrapper: "ce-code",
+      textarea: "ce-code__textarea"
+    }, this.nodes = {
+      holder: null,
+      textarea: null
+    }, this.data = {
+      code: t.code ?? ""
+    }, this.nodes.holder = this.drawView();
+  }
+  /**
+   * Return Tool's view
+   * @returns this.nodes.holder - Code's wrapper
+   */
+  render() {
+    return this.nodes.holder;
+  }
+  /**
+   * Extract Tool's data from the view
+   * @param codeWrapper - CodeTool's wrapper, containing textarea with code
+   * @returns - saved plugin code
+   */
+  save(t) {
+    return {
+      code: t.querySelector("textarea").value
+    };
+  }
+  /**
+   * onPaste callback fired from Editor`s core
+   * @param event - event with pasted content
+   */
+  onPaste(t) {
+    switch (t.type) {
+      case "tag": {
+        const e = t.detail.data;
+        this.handleHTMLPaste(e);
+        break;
+      }
+    }
+  }
+  /**
+   * Returns Tool`s data from private property
+   * @returns
+   */
+  get data() {
+    return this._data;
+  }
+  /**
+   * Set Tool`s data to private property and update view
+   * @param data - saved tool data
+   */
+  set data(t) {
+    this._data = t, this.nodes.textarea && (this.nodes.textarea.value = t.code);
+  }
+  /**
+   * Get Tool toolbox settings.
+   * Provides the icon and title to display in the toolbox for the CodeTool.
+   * @returns An object containing:
+   * - icon: SVG representation of the Tool's icon
+   * - title: Title to show in the toolbox
+   */
+  static get toolbox() {
+    return {
+      icon: h,
+      title: "Code"
+    };
+  }
+  /**
+   * Default placeholder for CodeTool's textarea
+   * @returns
+   */
+  static get DEFAULT_PLACEHOLDER() {
+    return "Enter a code";
+  }
+  /**
+   *  Used by Editor.js paste handling API.
+   *  Provides configuration to handle CODE tag.
+   * @returns
+   */
+  static get pasteConfig() {
+    return {
+      tags: ["pre"]
+    };
+  }
+  /**
+   * Automatic sanitize config
+   * @returns
+   */
+  static get sanitize() {
+    return {
+      code: !0
+      // Allow HTML tags
+    };
+  }
+  /**
+   * Handles Tab key pressing (adds/removes indentations)
+   * @param event - keydown
+   */
+  tabHandler(t) {
+    t.stopPropagation(), t.preventDefault();
+    const e = t.target, a = t.shiftKey, s = e.selectionStart, r = e.value, n = "  ";
+    let i;
+    if (!a)
+      i = s + n.length, e.value = r.substring(0, s) + n + r.substring(s);
+    else {
+      const o = c(r, s);
+      if (r.substr(o, n.length) !== n)
+        return;
+      e.value = r.substring(0, o) + r.substring(o + n.length), i = s - n.length;
+    }
+    e.setSelectionRange(i, i);
+  }
+  /**
+   * Create Tool's view
+   * @returns
+   */
+  drawView() {
+    const t = document.createElement("div"), e = document.createElement("textarea");
+    return t.classList.add(this.CSS.baseClass, this.CSS.wrapper), e.classList.add(this.CSS.textarea, this.CSS.input), e.value = this.data.code, e.placeholder = this.placeholder, this.readOnly && (e.disabled = !0), t.appendChild(e), e.addEventListener("keydown", (a) => {
+      switch (a.code) {
+        case "Tab":
+          this.tabHandler(a);
+          break;
+      }
+    }), this.nodes.textarea = e, t;
+  }
+  /**
+   * Extracts the code content from the pasted element's innerHTML and populates the tool's data.
+   * @param element - pasted HTML element
+   */
+  handleHTMLPaste(t) {
+    this.data = {
+      code: t.innerHTML
+    };
+  }
+}
+export {
+  d as default
+};

data/app/assets/javascripts/pressroom/vendor/delimiter.js

@@ -0,0 +1,98 @@
+(function(){"use strict";try{if(typeof document<"u"){var e=document.createElement("style");e.appendChild(document.createTextNode('.ce-delimiter{line-height:1.6em;width:100%;text-align:center}.ce-delimiter:before{display:inline-block;content:"***";font-size:30px;line-height:65px;height:30px;letter-spacing:.2em}')),document.head.appendChild(e)}}catch(t){console.error("vite-plugin-css-injected-by-js",t)}})();
+const r = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none" viewBox="0 0 24 24"><line x1="6" x2="10" y1="12" y2="12" stroke="currentColor" stroke-linecap="round" stroke-width="2"/><line x1="14" x2="18" y1="12" y2="12" stroke="currentColor" stroke-linecap="round" stroke-width="2"/></svg>';
+/**
+ * Delimiter Block for the Editor.js.
+ *
+ * @author CodeX (team@ifmo.su)
+ * @copyright CodeX 2018
+ * @license The MIT License (MIT)
+ * @version 2.0.0
+ */
+class n {
+  /**
+   * Notify core that read-only mode is supported
+   * @return {boolean}
+   */
+  static get isReadOnlySupported() {
+    return !0;
+  }
+  /**
+   * Allow Tool to have no content
+   * @return {boolean}
+   */
+  static get contentless() {
+    return !0;
+  }
+  /**
+   * Render plugin`s main Element and fill it with saved data
+   *
+   * @param {{data: DelimiterData, config: object, api: object}}
+   *   data — previously saved data
+   *   config - user config for Tool
+   *   api - Editor.js API
+   */
+  constructor({ data: t, config: s, api: e }) {
+    this.api = e, this._CSS = {
+      block: this.api.styles.block,
+      wrapper: "ce-delimiter"
+    }, this._element = this.drawView(), this.data = t;
+  }
+  /**
+   * Create Tool's view
+   * @return {HTMLDivElement}
+   * @private
+   */
+  drawView() {
+    let t = document.createElement("div");
+    return t.classList.add(this._CSS.wrapper, this._CSS.block), t;
+  }
+  /**
+   * Return Tool's view
+   * @returns {HTMLDivElement}
+   * @public
+   */
+  render() {
+    return this._element;
+  }
+  /**
+   * Extract Tool's data from the view
+   * @param {HTMLDivElement} toolsContent - Paragraph tools rendered view
+   * @returns {DelimiterData} - saved data
+   * @public
+   */
+  save(t) {
+    return {};
+  }
+  /**
+   * Get Tool toolbox settings
+   * icon - Tool icon's SVG
+   * title - title to show in toolbox
+   *
+   * @return {{icon: string, title: string}}
+   */
+  static get toolbox() {
+    return {
+      icon: r,
+      title: "Delimiter"
+    };
+  }
+  /**
+   * Delimiter onPaste configuration
+   *
+   * @public
+   */
+  static get pasteConfig() {
+    return { tags: ["HR"] };
+  }
+  /**
+   * On paste callback that is fired from Editor
+   *
+   * @param {PasteEvent} event - event with pasted data
+   */
+  onPaste(t) {
+    this.data = {};
+  }
+}
+export {
+  n as default
+};