katalyst-navigation 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0149b9c1ba7f7a1ecfcc1e085fbe33b2b0eb11d0d5372b743f05d0261daf88e3'
+  data.tar.gz: 2648b6258ac7a7f2b4800f0b1371687cba043d9d4a647f5753076bc8a1b04327
+SHA512:
+  metadata.gz: d31db0f384749242de03b5bc04da8a0d3137092c702a3c4eda5769bf53fe1f764bb457bd672af5a60c1f3ef1daa22a7d2830e4f53b78b0f2161bdc2db675b54a
+  data.tar.gz: 615fd376052d6b4e48351ef2d0d144a8bd66bfbe615d01b65eed57eb90a1679f4eae630abddbfe82d3aff9f1a47baa09987f4c3a536625f5ea00849612109805

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [1.0.0] - 2022-09-05
+
+- Initial release

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,25 @@
+# Navigation
+
+Generates and edits navigation menus.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add katalyst-navigation
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install katalyst-navigation
+
+## Usage
+
+This gem is still experimental and is not yet ready for public consumption. See dummy app for example usage.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/katalyst/navigation.
+
+## 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-navigation.js

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

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

@@ -0,0 +1,45 @@
+import { Controller } from "@hotwired/stimulus";
+import Item from "utils/navigation/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: "navigation" });
+  }
+}

data/app/assets/javascripts/controllers/navigation/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='navigation--editor--list'] > *");
+  }
+
+  reindex() {
+    this.dispatch("reindex", { bubbles: true, prefix: "navigation" });
+  }
+
+  reset() {
+    this.dispatch("reset", { bubbles: true, prefix: "navigation" });
+  }
+}
+
+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/navigation/editor/menu_controller.js

@@ -0,0 +1,110 @@
+import { Controller } from "@hotwired/stimulus";
+
+import Item from "utils/navigation/editor/item";
+import Menu from "utils/navigation/editor/menu";
+import RulesEngine from "utils/navigation/editor/rules-engine";
+
+export default class MenuController extends Controller {
+  static targets = ["menu"];
+
+  connect() {
+    this.state = this.menu.state;
+
+    this.reindex();
+  }
+
+  get menu() {
+    return new Menu(this.menuTarget);
+  }
+
+  reindex() {
+    this.menu.reindex();
+    this.#update();
+  }
+
+  reset() {
+    this.menu.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.menu.items.forEach((item) => engine.update(item));
+
+      this.#notifyChange();
+    }, 0);
+  }
+
+  #notifyChange() {
+    this.dispatch("change", {
+      bubbles: true,
+      prefix: "navigation",
+      detail: { dirty: this.#isDirty() },
+    });
+  }
+
+  #isDirty() {
+    return this.menu.state !== this.state;
+  }
+}
+
+function getEventItem(event) {
+  return new Item(event.target.closest("[data-navigation-item]"));
+}

data/app/assets/javascripts/controllers/navigation/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/navigation/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/navigation/editor/item.js

@@ -0,0 +1,245 @@
+export default class Item {
+  /**
+   * Sort items by their index.
+   *
+   * @param a {Item}
+   * @param b {Item}
+   * @returns {number}
+   */
+  static comparator(a, b) {
+    return a.index - b.index;
+  }
+
+  /**
+   * @param node {Element} li[data-navigation-index]
+   */
+  constructor(node) {
+    this.node = node;
+  }
+
+  /**
+   * @returns {String} id of the node's item (from data attributes)
+   */
+  get itemId() {
+    return this.node.dataset[`navigationItemId`];
+  }
+
+  get #itemIdInput() {
+    return this.node.querySelector(`input[name$="[id]"]`);
+  }
+
+  /**
+   * @param itemId {String} id
+   */
+  set itemId(id) {
+    if (this.itemId === id) return;
+
+    this.node.dataset[`navigationItemId`] = `${id}`;
+    this.#itemIdInput.value = `${id}`;
+  }
+
+  /**
+   * @returns {number} logical nesting depth of node in menu
+   */
+  get depth() {
+    return parseInt(this.node.dataset[`navigationDepth`]);
+  }
+
+  get #depthInput() {
+    return this.node.querySelector(`input[name$="[depth]"]`);
+  }
+
+  /**
+   * @param depth {number} depth >= 0
+   */
+  set depth(depth) {
+    if (this.depth === depth) return;
+
+    this.node.dataset[`navigationDepth`] = `${depth}`;
+    this.#depthInput.value = `${depth}`;
+  }
+
+  /**
+   * @returns {number} logical index of node in menu (pre-order traversal)
+   */
+  get index() {
+    return parseInt(this.node.dataset[`navigationIndex`]);
+  }
+
+  get #indexInput() {
+    return this.node.querySelector(`input[name$="[index]"]`);
+  }
+
+  /**
+   * @param index {number} index >= 0
+   */
+  set index(index) {
+    if (this.index === index) return;
+
+    this.node.dataset[`navigationIndex`] = `${index}`;
+    this.#indexInput.value = `${index}`;
+  }
+
+  /**
+   * @returns {Item} nearest neighbour (index - 1)
+   */
+  get previousItem() {
+    let sibling = this.node.previousElementSibling;
+    if (sibling) return new Item(sibling);
+  }
+
+  /**
+   * @returns {Item} nearest neighbour (index + 1)
+   */
+  get nextItem() {
+    let sibling = this.node.nextElementSibling;
+    if (sibling) return new Item(sibling);
+  }
+
+  /**
+   * @returns {boolean} true if this item has any collapsed children
+   */
+  hasCollapsedDescendants() {
+    let childrenList = this.#childrenListElement;
+    return !!childrenList && childrenList.children.length > 0;
+  }
+
+  /**
+   * @returns {boolean} true if this item has any expanded children
+   */
+  hasExpandedDescendants() {
+    let sibling = this.nextItem;
+    return !!sibling && sibling.depth > this.depth;
+  }
+
+  /**
+   * Recursively traverse the node and its descendants.
+   *
+   * @callback {Item}
+   */
+  traverse(callback) {
+    // capture descendants before traversal in case of side-effects
+    // specifically, setting depth affects calculation
+    const collapsed = this.#collapsedChildren;
+    const expanded = this.#expandedDescendants;
+
+    callback(this);
+    collapsed.forEach((item) => item.traverse(callback));
+    expanded.forEach((item) => item.traverse(callback));
+  }
+
+  /**
+   * Collapses visible (logical) children into this element's hidden children
+   * list, creating it if it doesn't already exist.
+   */
+  collapse() {
+    let listElement = this.#childrenListElement;
+
+    if (!listElement) listElement = createChildrenList(this.node);
+
+    this.#expandedDescendants.forEach((child) =>
+      listElement.appendChild(child.node)
+    );
+  }
+
+  /**
+   * Moves any collapsed children back into the parent menu.
+   */
+  expand() {
+    if (!this.hasCollapsedDescendants()) return;
+
+    Array.from(this.#childrenListElement.children)
+      .reverse()
+      .forEach((node) => {
+        this.node.insertAdjacentElement("afterend", node);
+      });
+  }
+
+  /**
+   * Sets the state of a given rule on the target node.
+   *
+   * @param rule {String}
+   * @param deny {boolean}
+   */
+  toggleRule(rule, deny = false) {
+    if (this.node.dataset.hasOwnProperty(rule) && !deny)
+      delete this.node.dataset[rule];
+    if (!this.node.dataset.hasOwnProperty(rule) && deny)
+      this.node.dataset[rule] = "";
+
+    if (rule === "denyDrag") {
+      if (!this.node.hasAttribute("draggable") && !deny) {
+        this.node.setAttribute("draggable", "true");
+      }
+      if (this.node.hasAttribute("draggable") && deny) {
+        this.node.removeAttribute("draggable");
+      }
+    }
+  }
+
+  /**
+   * Detects turbo item changes by comparing the dataset id with the input
+   */
+  hasItemIdChanged() {
+    return !(this.#itemIdInput.value === this.itemId);
+  }
+
+  /**
+   * Updates inputs, in case they don't match the data values, e.g., when the
+   * nested inputs have been hot-swapped by turbo with data from the server.
+   *
+   * Updates itemId from input as that is the canonical source.
+   */
+  updateAfterChange() {
+    this.itemId = this.#itemIdInput.value;
+    this.#indexInput.value = this.index;
+    this.#depthInput.value = this.depth;
+  }
+
+  /**
+   * Finds the dom container for storing collapsed (hidden) children, if present.
+   *
+   * @returns {Element} ol[data-navigation-children]
+   */
+  get #childrenListElement() {
+    return this.node.querySelector(`:scope > [data-navigation-children]`);
+  }
+
+  get #expandedDescendants() {
+    const descendants = [];
+
+    let sibling = this.nextItem;
+    while (sibling && sibling.depth > this.depth) {
+      descendants.push(sibling);
+      sibling = sibling.nextItem;
+    }
+
+    return descendants;
+  }
+
+  get #collapsedChildren() {
+    if (!this.hasCollapsedDescendants()) return [];
+
+    return Array.from(this.#childrenListElement.children).map(
+      (node) => new Item(node)
+    );
+  }
+}
+
+/**
+ * Finds or creates a dom container for storing collapsed (hidden) children.
+ *
+ * @param node {Element} li[data-navigation-index]
+ * @returns {Element} ol[data-navigation-children]
+ */
+function createChildrenList(node) {
+  const childrenList = document.createElement("ol");
+  childrenList.setAttribute("class", "hidden");
+
+  // if objectType is "rich-content" set richContentChildren as a data attribute
+  childrenList.dataset[`navigationChildren`] = "";
+
+  node.appendChild(childrenList);
+
+  return childrenList;
+}

data/app/assets/javascripts/utils/navigation/editor/menu.js

@@ -0,0 +1,54 @@
+import Item from "./item";
+
+/**
+ * @param nodes {NodeList}
+ * @returns {Item[]}
+ */
+function createItemList(nodes) {
+  return Array.from(nodes).map((node) => new Item(node));
+}
+
+export default class Menu {
+  /**
+   * @param node {Element} navigation editor list
+   */
+  constructor(node) {
+    this.node = node;
+  }
+
+  /**
+   * @return {Item[]} an ordered list of all items in the menu
+   */
+  get items() {
+    return createItemList(
+      this.node.querySelectorAll("[data-navigation-index]")
+    );
+  }
+
+  /**
+   *  @return {String} a serialized description of the structure of the menu
+   */
+  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);
+    });
+  }
+}