katalyst-content 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dabae0594160eb1ebafdd3501b5d521113fdcc8bde6f36eede4296314297255d
+  data.tar.gz: aace7d35cd049a4c3fcf140f21099d5d04d03020a1935402e8999fa82c368823
+SHA512:
+  metadata.gz: 452af88132002902aef2edfa6858e772a4985ea069cc6b1726c4acd9f3f2594fb84bf2e35a3377d233c5cfe1411caa5c7fc86c795b52d6c648d3a9c80bf616fe
+  data.tar.gz: 1077d2f70a588105436e553b186f4cd3239a250ef36c2f10e15827973b8ea8375ca62b9b5c227d432f8642ef63a8ccdde832a6c89c482df6b99c79749811e78f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Katalyst Interactive
+
+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,95 @@
+# Katalyst::Content
+
+Katalyst Content provides tools for creating and publishing content on Rails
+applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'katalyst-content'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install katalyst-content
+
+## Usage
+
+Content can be added to multiple models in your application. These examples
+assume a `Page` model.
+
+Assuming your model already exists, create a table for versions and add
+published and draft version columns to your model. For example, if you have a
+pages model:
+
+```ruby
+class CreatePageVersions < ActiveRecord::Migration[7.0]
+  def change
+    create_table :page_versions do |t|
+      t.references :parent, foreign_key: { to_table: :pages }, null: false
+      t.json :nodes
+
+      t.timestamps
+    end
+
+    change_table :pages do |t|
+      t.references :published_version, foreign_key: { to_table: :page_versions }
+      t.references :draft_version, foreign_key: { to_table: :page_versions }
+    end
+  end
+end
+```
+
+Next, include the `Katalyst::Content` concerns into your model, and add a nested
+model for storing content version information:
+
+```ruby
+class Page < ApplicationRecord
+  include Katalyst::Content::Container
+
+  class Version < ApplicationRecord
+    include Katalyst::Content::Version
+  end
+end
+```
+
+You may also want to configure your factory to add container information to
+items:
+
+```ruby
+FactoryBot.define do
+  factory :page do
+    title { Faker::Beer.unique.name }
+    slug { title.parameterize }
+
+    after(:build) do |page, _context|
+      page.items.each { |item| item.container = page }
+    end
+
+    after(:create) do |page, _context|
+      page.items_attributes = page.items.map.with_index { |item, index| { id: item.id, index: index, depth: 0 } }
+      page.publish!
+    end
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `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/katalyst/content.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/config/katalyst-content.js

@@ -0,0 +1 @@
+//= link_tree ../javascripts

data/app/assets/javascripts/controllers/content/editor/container_controller.js

@@ -0,0 +1,113 @@
+import { Controller } from "@hotwired/stimulus";
+
+import Item from "utils/content/editor/item";
+import Container from "utils/content/editor/container";
+import RulesEngine from "utils/content/editor/rules-engine";
+
+export default class ContainerController extends Controller {
+  static targets = ["container"];
+  static values = {
+    maxDepth: Number,
+  };
+
+  connect() {
+    this.state = this.container.state;
+
+    this.reindex();
+  }
+
+  get container() {
+    return new Container(this.containerTarget);
+  }
+
+  reindex() {
+    this.container.reindex();
+    this.#update();
+  }
+
+  reset() {
+    this.container.reset();
+  }
+
+  remove(event) {
+    const item = getEventItem(event);
+
+    item.node.remove();
+
+    this.#update();
+    event.preventDefault();
+  }
+
+  nest(event) {
+    const item = getEventItem(event);
+
+    item.traverse((child) => {
+      child.depth += 1;
+    });
+
+    this.#update();
+    event.preventDefault();
+  }
+
+  deNest(event) {
+    const item = getEventItem(event);
+
+    item.traverse((child) => {
+      child.depth -= 1;
+    });
+
+    this.#update();
+    event.preventDefault();
+  }
+
+  collapse(event) {
+    const item = getEventItem(event);
+
+    item.collapse();
+
+    this.#update();
+    event.preventDefault();
+  }
+
+  expand(event) {
+    const item = getEventItem(event);
+
+    item.expand();
+
+    this.#update();
+    event.preventDefault();
+  }
+
+  /**
+   * Re-apply rules to items to enable/disable appropriate actions.
+   */
+  #update() {
+    // debounce requests to ensure that we only update once per tick
+    this.updateRequested = true;
+    setTimeout(() => {
+      if (!this.updateRequested) return;
+
+      this.updateRequested = false;
+      const engine = new RulesEngine(this.maxDepthValue);
+      this.container.items.forEach((item) => engine.update(item));
+
+      this.#notifyChange();
+    }, 0);
+  }
+
+  #notifyChange() {
+    this.dispatch("change", {
+      bubbles: true,
+      prefix: "content",
+      detail: { dirty: this.#isDirty() },
+    });
+  }
+
+  #isDirty() {
+    return this.container.state !== this.state;
+  }
+}
+
+function getEventItem(event) {
+  return new Item(event.target.closest("[data-content-item]"));
+}

data/app/assets/javascripts/controllers/content/editor/item_controller.js

@@ -0,0 +1,45 @@
+import { Controller } from "@hotwired/stimulus";
+import Item from "utils/content/editor/item";
+
+export default class ItemController extends Controller {
+  get item() {
+    return new Item(this.li);
+  }
+
+  get ol() {
+    return this.element.closest("ol");
+  }
+
+  get li() {
+    return this.element.closest("li");
+  }
+
+  connect() {
+    if (this.element.dataset.hasOwnProperty("delete")) {
+      this.remove();
+    }
+    // if index is not already set, re-index will set it
+    else if (!(this.item.index >= 0)) {
+      this.reindex();
+    }
+    // if item has been replaced via turbo, re-index will run the rules engine
+    // update our depth and index with values from the li's data attributes
+    else if (this.item.hasItemIdChanged()) {
+      this.item.updateAfterChange();
+      this.reindex();
+    }
+  }
+
+  remove() {
+    // capture ol
+    const ol = this.ol;
+    // remove self from dom
+    this.li.remove();
+    // reindex ol
+    this.reindex();
+  }
+
+  reindex() {
+    this.dispatch("reindex", { bubbles: true, prefix: "content" });
+  }
+}

data/app/assets/javascripts/controllers/content/editor/list_controller.js

@@ -0,0 +1,105 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class ListController extends Controller {
+  dragstart(event) {
+    if (this.element !== event.target.parentElement) return;
+
+    const target = event.target;
+    event.dataTransfer.effectAllowed = "move";
+
+    // update element style after drag has begun
+    setTimeout(() => (target.dataset.dragging = ""));
+  }
+
+  dragover(event) {
+    const item = this.dragItem();
+    if (!item) return;
+
+    swap(this.dropTarget(event.target), item);
+
+    event.preventDefault();
+    return true;
+  }
+
+  dragenter(event) {
+    event.preventDefault();
+
+    if (event.dataTransfer.effectAllowed === "copy" && !this.dragItem()) {
+      const item = document.createElement("li");
+      item.dataset.dragging = "";
+      item.dataset.newItem = "";
+      this.element.prepend(item);
+    }
+  }
+
+  dragleave(event) {
+    const item = this.dragItem();
+    const related = this.dropTarget(event.relatedTarget);
+
+    // ignore if item is not set or we're moving into a valid drop target
+    if (!item || related) return;
+
+    // remove item if it's a new item
+    if (item.dataset.hasOwnProperty("newItem")) {
+      item.remove();
+    }
+  }
+
+  drop(event) {
+    const item = this.dragItem();
+
+    if (!item) return;
+
+    event.preventDefault();
+    delete item.dataset.dragging;
+    swap(this.dropTarget(event.target), item);
+
+    if (item.dataset.hasOwnProperty("newItem")) {
+      const template = document.createElement("template");
+      template.innerHTML = event.dataTransfer.getData("text/html");
+      const newItem = template.content.querySelector("li");
+
+      this.element.replaceChild(newItem, item);
+      setTimeout(() =>
+        newItem.querySelector("[role='button'][value='edit']").click()
+      );
+    }
+
+    this.reindex();
+  }
+
+  dragend() {
+    const item = this.dragItem();
+    if (!item) return;
+
+    delete item.dataset.dragging;
+    this.reset();
+  }
+
+  dragItem() {
+    return this.element.querySelector("[data-dragging]");
+  }
+
+  dropTarget(e) {
+    return e && e.closest("[data-controller='content--editor--list'] > *");
+  }
+
+  reindex() {
+    this.dispatch("reindex", { bubbles: true, prefix: "content" });
+  }
+
+  reset() {
+    this.dispatch("reset", { bubbles: true, prefix: "content" });
+  }
+}
+
+function swap(target, item) {
+  if (target && target !== item) {
+    const positionComparison = target.compareDocumentPosition(item);
+    if (positionComparison & Node.DOCUMENT_POSITION_FOLLOWING) {
+      target.insertAdjacentElement("beforebegin", item);
+    } else if (positionComparison & Node.DOCUMENT_POSITION_PRECEDING) {
+      target.insertAdjacentElement("afterend", item);
+    }
+  }
+}

data/app/assets/javascripts/controllers/content/editor/new_item_controller.js

@@ -0,0 +1,12 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class NewItemController extends Controller {
+  static targets = ["template"];
+
+  dragstart(event) {
+    if (this.element !== event.target) return;
+
+    event.dataTransfer.setData("text/html", this.templateTarget.innerHTML);
+    event.dataTransfer.effectAllowed = "copy";
+  }
+}

data/app/assets/javascripts/controllers/content/editor/status_bar_controller.js

@@ -0,0 +1,22 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class StatusBarController extends Controller {
+  connect() {
+    // cache the version's state in the controller on connect
+    this.versionState = this.element.dataset.state;
+  }
+
+  change(e) {
+    if (e.detail && e.detail.hasOwnProperty("dirty")) {
+      this.update(e.detail);
+    }
+  }
+
+  update({ dirty }) {
+    if (dirty) {
+      this.element.dataset.state = "dirty";
+    } else {
+      this.element.dataset.state = this.versionState;
+    }
+  }
+}

data/app/assets/javascripts/utils/content/editor/container.js

@@ -0,0 +1,52 @@
+import Item from "utils/content/editor/item";
+
+/**
+ * @param nodes {NodeList}
+ * @returns {Item[]}
+ */
+function createItemList(nodes) {
+  return Array.from(nodes).map((node) => new Item(node));
+}
+
+export default class Container {
+  /**
+   * @param node {Element} content editor list
+   */
+  constructor(node) {
+    this.node = node;
+  }
+
+  /**
+   * @return {Item[]} an ordered list of all items in the container
+   */
+  get items() {
+    return createItemList(this.node.querySelectorAll("[data-content-index]"));
+  }
+
+  /**
+   *  @return {String} a serialized description of the structure of the container
+   */
+  get state() {
+    const inputs = this.node.querySelectorAll("li input[type=hidden]");
+    return Array.from(inputs)
+      .map((e) => e.value)
+      .join("/");
+  }
+
+  /**
+   * Set the index of items based on their current position.
+   */
+  reindex() {
+    this.items.map((item, index) => (item.index = index));
+  }
+
+  /**
+   * Resets the order of items to their defined index.
+   * Useful after an aborted drag.
+   */
+  reset() {
+    this.items.sort(Item.comparator).forEach((item) => {
+      this.node.appendChild(item.node);
+    });
+  }
+}