katalyst-navigation 1.0.0

data/app/helpers/katalyst/navigation/editor/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module Editor
+      class Base
+        MENU_CONTROLLER       = "navigation--editor--menu"
+        LIST_CONTROLLER       = "navigation--editor--list"
+        ITEM_CONTROLLER       = "navigation--editor--item"
+        STATUS_BAR_CONTROLLER = "navigation--editor--status-bar"
+        NEW_ITEM_CONTROLLER   = "navigation--editor--new-item"
+
+        ATTRIBUTES_SCOPE = "menu[items_attributes][]"
+        TURBO_FRAME      = "navigation--editor--item-frame"
+
+        attr_accessor :template, :menu
+
+        delegate_missing_to :template
+
+        def initialize(template, menu)
+          self.template = template
+          self.menu     = menu
+        end
+
+        def menu_form_id
+          dom_id(menu, :items)
+        end
+
+        private
+
+        def add_option(options, key, *path)
+          if path.length > 1
+            add_option(options[key] ||= {}, *path)
+          else
+            options[key] = [options[key], *path].compact.join(" ")
+          end
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/editor/item.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module Editor
+      class Item < Base
+        attr_accessor :item
+
+        def build(item, **options, &block)
+          self.item = item
+          content_tag(:div, default_options(id: dom_id(item), **options)) do
+            concat(capture { yield self }) if block
+            concat fields(item)
+          end
+        end
+
+        def build_all(*items)
+          render partial:    "katalyst/navigation/menus/link_item",
+                 layout:     "katalyst/navigation/menus/navigation_menu_link",
+                 collection: items,
+                 as:         :item
+        end
+
+        def accordion_actions
+          tag.div role: "toolbar", data: { tree_accordion_controls: "" } do
+            concat tag.span(role: "button", value: "collapse",
+                            data: { action: "click->#{MENU_CONTROLLER}#collapse", title: "Collapse tree" })
+            concat tag.span(role: "button", value: "expand",
+                            data: { action: "click->#{MENU_CONTROLLER}#expand", title: "Expand tree" })
+          end
+        end
+
+        def item_actions
+          tag.div role: "toolbar", data: { tree_controls: "" } do
+            concat tag.span(role: "button", value: "de-nest",
+                            data: { action: "click->#{MENU_CONTROLLER}#deNest", title: "Outdent" })
+            concat tag.span(role: "button", value: "nest",
+                            data: { action: "click->#{MENU_CONTROLLER}#nest", title: "Indent" })
+            concat link_to("", edit_item_link,
+                           role: "button", title: "Edit", value: "edit",
+                           data: { turbo_frame: TURBO_FRAME })
+            concat tag.span(role: "button", value: "remove",
+                            data: { action: "click->#{MENU_CONTROLLER}#remove", title: "Remove" })
+          end
+        end
+
+        def edit_item_link
+          item.persisted? ? edit_menu_item_path(item.menu, item) : new_menu_item_path(item.menu, type: item.type)
+        end
+
+        def fields(item)
+          template.fields(ATTRIBUTES_SCOPE, model: item, index: nil, skip_default_ids: true) do |f|
+            concat f.hidden_field(:id)
+            concat f.hidden_field(:depth)
+            concat f.hidden_field(:index)
+          end
+        end
+
+        private
+
+        def default_options(options)
+          add_option(options, :data, :controller, ITEM_CONTROLLER)
+
+          options
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/editor/list.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module Editor
+      class List < Base
+        ACTIONS = <<~ACTIONS.gsub(/\s+/, " ").freeze
+          dragstart->#{LIST_CONTROLLER}#dragstart
+          dragover->#{LIST_CONTROLLER}#dragover
+          dragenter->#{LIST_CONTROLLER}#dragenter
+          dragleave->#{LIST_CONTROLLER}#dragleave
+          drop->#{LIST_CONTROLLER}#drop
+          dragend->#{LIST_CONTROLLER}#dragend
+        ACTIONS
+
+        def build(options, &_block)
+          content_tag :ol, default_options(id: menu_form_id, **options) do
+            yield self
+          end
+        end
+
+        def items(*items)
+          render partial:    "katalyst/navigation/menus/item",
+                 layout:     "katalyst/navigation/menus/list_item",
+                 collection: items,
+                 as:         :item
+        end
+
+        private
+
+        def default_options(options)
+          add_option(options, :data, :controller, LIST_CONTROLLER)
+          add_option(options, :data, :action, ACTIONS)
+          add_option(options, :data, :"#{MENU_CONTROLLER}_target", "menu")
+
+          options
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/editor/menu.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module Editor
+      class Menu < Base
+        ACTIONS = <<~ACTIONS.gsub(/\s+/, " ").freeze
+          submit->#{MENU_CONTROLLER}#reindex
+          navigation:reindex->#{MENU_CONTROLLER}#reindex
+          navigation:reset->#{MENU_CONTROLLER}#reset
+        ACTIONS
+
+        def build(options)
+          form_with(model: menu, **default_options(id: menu_form_id, **options)) do |form|
+            concat hidden_input
+            concat(capture { yield form })
+          end
+        end
+
+        private
+
+        # Hidden input ensures that if the menu is empty then the controller
+        # receives an empty array.
+        def hidden_input
+          tag.input(type: "hidden", name: "#{Item::ATTRIBUTES_SCOPE}[id]")
+        end
+
+        def default_options(options)
+          add_option(options, :data, :controller, MENU_CONTROLLER)
+          add_option(options, :data, :action, ACTIONS)
+
+          options
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/editor/new_item.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module Editor
+      class NewItem < Base
+        ACTIONS = <<~ACTIONS.gsub(/\s+/, " ").freeze
+          dragstart->#{NEW_ITEM_CONTROLLER}#dragstart
+        ACTIONS
+
+        def build(item, **options, &block)
+          capture do
+            concat(content_tag(:div, **default_options(options)) do
+              concat capture(&block)
+              concat item_template(item)
+            end)
+            concat turbo_replace_placeholder(item)
+          end
+        end
+
+        # Remove items that are incomplete when rendering new items, this
+        # causes incomplete items to be removed from the list when the user
+        # cancels adding a new item by pressing 'discard' in the new item form.
+        def turbo_replace_placeholder(item)
+          turbo_stream.replace dom_id(item) do
+            navigation_editor_item(item: item, data: { delete: "" })
+          end
+        end
+
+        # Template is stored inside the new item dom, and copied into drag
+        # events when the user initiates drag so that it can be copied into the
+        # editor list on drop.
+        def item_template(item)
+          content_tag(:template, data: { "#{NEW_ITEM_CONTROLLER}-target" => "template" }) do
+            navigation_editor_items(item: item)
+          end
+        end
+
+        private
+
+        def default_options(options)
+          add_option(options, :draggable, true)
+          add_option(options, :role, "listitem")
+          add_option(options, :data, :turbo_frame, TURBO_FRAME)
+          add_option(options, :data, :controller, NEW_ITEM_CONTROLLER)
+          add_option(options, :data, :action, ACTIONS)
+
+          options
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/editor/status_bar.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module Editor
+      class StatusBar < Base
+        ACTIONS = <<~ACTIONS.gsub(/\s+/, " ").freeze
+          navigation:change@document->#{STATUS_BAR_CONTROLLER}#change
+        ACTIONS
+
+        def build(**options)
+          content_tag(:div, default_options(**options)) do
+            concat status(:published, last_update: l(menu.updated_at, format: :short))
+            concat status(:draft)
+            concat status(:dirty)
+            concat actions
+          end
+        end
+
+        def status(state, **options)
+          tag.span(t("views.katalyst.navigation.editor.#{state}_html", **options),
+                   class: "status-text",
+                   data:  { state => "" })
+        end
+
+        def actions
+          content_tag(:menu) do
+            concat action(:discard, class: "button button--text")
+            concat action(:revert, class: "button button--text") if menu.state == :draft
+            concat action(:save, class: "button button--secondary")
+            concat action(:publish, class: "button button--primary")
+          end
+        end
+
+        def action(action, **options)
+          tag.li do
+            button_tag(t("views.katalyst.navigation.editor.#{action}"),
+                       name:  "commit",
+                       value: action,
+                       form:  menu_form_id,
+                       **options)
+          end
+        end
+
+        private
+
+        def default_options(**options)
+          add_option(options, :data, :controller, STATUS_BAR_CONTROLLER)
+          add_option(options, :data, :action, ACTIONS)
+          add_option(options, :data, :state, menu.state)
+
+          options
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/editor_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module EditorHelper
+      def navigation_editor_new_items(menu)
+        [
+          Link.new(menu: menu),
+          Button.new(menu: menu),
+        ]
+      end
+
+      def navigation_editor_menu(menu:, **options, &block)
+        Editor::Menu.new(self, menu).build(options, &block)
+      end
+
+      def navigation_editor_list(menu:, items: menu.draft_items, **options)
+        Editor::List.new(self, menu).build(options) do |list|
+          list.items(*items) if items.present?
+        end
+      end
+
+      # Generate items without their list wrapper, similar to form_with/fields
+      def navigation_editor_items(item:, menu: item.menu)
+        Editor::List.new(self, menu).items(item)
+      end
+
+      # Gene
+      def navigation_editor_new_item(item:, menu: item.menu, **options, &block)
+        Editor::NewItem.new(self, menu).build(item, **options, &block)
+      end
+
+      def navigation_editor_item(item:, menu: item.menu, **options, &block)
+        Editor::Item.new(self, menu).build(item, **options, &block)
+      end
+
+      def navigation_editor_item_fields(item:, menu: item.menu)
+        Editor::Item.new(self, menu).fields(item)
+      end
+
+      def navigation_editor_status_bar(menu:, **options)
+        Editor::StatusBar.new(self, menu).build(**options)
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/frontend/builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module Frontend
+      class Builder
+        attr_accessor :template, :menu_options, :list_options, :item_options
+
+        delegate_missing_to :@template
+
+        def initialize(template, menu: {}, list: {}, item: {})
+          self.template     = template
+          self.menu_options = menu
+          self.list_options = list
+          self.item_options = item
+        end
+
+        def render(tree)
+          content_tag(:ul, menu_options) do
+            tree.each do |item|
+              concat render_item(item)
+            end
+          end
+        end
+
+        def render_item(item)
+          return unless item.visible?
+
+          content_tag :li, item_options do
+            concat public_send("render_#{item.model_name.param_key}", item)
+            concat render_list(item.children) if item.children.any?
+          end
+        end
+
+        def render_list(items)
+          content_tag :ul, list_options do
+            items.each do |child|
+              concat render_item(child)
+            end
+          end
+        end
+
+        def render_link(link)
+          link_to(link.title, link.url, item_options)
+        end
+
+        def render_button(link)
+          link_to(link.title, link.url, **item_options, method: link.http_method)
+        end
+      end
+    end
+  end
+end

data/app/helpers/katalyst/navigation/frontend_helper.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module FrontendHelper
+      mattr_accessor :navigation_builder
+
+      # Render a navigation menu. Caches based on the published version's id.
+      #
+      # @param(menu: Katalyst::Navigation::Menu)
+      # @return Structured HTML containing top level + nested navigation links
+      def render_navigation_menu(menu, item: {}, list: {}, **options)
+        return unless menu&.published_version&.present?
+
+        cache menu.published_version do
+          builder = default_navigation_builder_class.new(self, menu: options, item: item, list: list)
+          concat builder.render(menu.published_tree)
+        end
+      end
+
+      # Render items without a wrapper list, useful for inline rendering of items
+      #
+      # @param(items: [Katalyst::Navigation::Item])
+      # @return Structured HTML containing top level + nested navigation links
+      def render_navigation_items(items, list: {}, **options)
+        builder = default_navigation_builder_class.new(self, item: options, list: list)
+        capture do
+          items.each do |item|
+            concat builder.render_item(item)
+          end
+        end
+      end
+
+      private
+
+      def default_navigation_builder_class
+        builder = controller.try(:default_navigation_builder) || Frontend::Builder
+        builder.respond_to?(:constantize) ? builder.constantize : builder
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/navigation/garbage_collection.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module GarbageCollection
+      extend ActiveSupport::Concern
+
+      included do
+        after_update :remove_stale_versions
+      end
+
+      def remove_stale_versions
+        transaction do
+          # find all the versions that are not linked to the menu
+          orphaned_versions = versions.inactive
+
+          next unless orphaned_versions.any?
+
+          # find links that are not included in active versions
+          orphaned_items = items.pluck(:id) - versions.active.pluck(:nodes).flat_map { |k| k.map(&:id) }.uniq
+
+          # delete orphaned links with a 2 hour grace period to allow for in-progress editing
+          items.where(id: orphaned_items, updated_at: ..2.hours.ago).destroy_all
+
+          # delete orphaned versions without a grace period as they can only be created by updates
+          orphaned_versions.destroy_all
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/navigation/has_tree.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    module HasTree
+      # Constructs a tree from an ordered list of items with depth.
+      #  * items that have higher depth than their predecessor are nested as `children`.
+      #  * items with the same depth become siblings.
+      def tree
+        items.reduce(Builder.new, &:add).tree
+      end
+
+      class Builder
+        attr_reader :current, :depth, :children, :tree
+
+        def initialize
+          @depth    = 0
+          @children = @tree = []
+        end
+
+        def add(node)
+          if node.depth == depth
+            node.parent = current
+            children << node
+            self
+          elsif node.depth > depth
+            push(children.last)
+            add(node)
+          else
+            pop
+            add(node)
+          end
+        end
+
+        private
+
+        attr_writer :current, :depth, :children
+
+        # Add node to the top of builder stacks
+        def push(node)
+          self.depth += 1
+          self.current  = node
+          self.children = node.children = []
+          node
+        end
+
+        # Remove current from builder stack
+        def pop
+          previous = current
+          self.depth -= 1
+          if depth.zero?
+            self.current  = nil
+            self.children = tree
+          else
+            self.current  = previous.parent
+            self.children = current.children
+          end
+          previous
+        end
+      end
+    end
+  end
+end

data/app/models/katalyst/navigation/button.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    # Renders an HTML button using `button_to`.
+    class Button < Item
+      HTTP_METHODS = %i[get post patch put delete].index_by(&:itself).freeze
+
+      enum method: HTTP_METHODS, _prefix: :http
+
+      validates :title, :url, :http_method, presence: true
+      validates :http_method, inclusion: { in: HTTP_METHODS.values.map(&:to_s) }
+    end
+  end
+end

data/app/models/katalyst/navigation/item.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    # STI base class for menu items (links and buttons)
+    class Item < ApplicationRecord
+      belongs_to :menu, inverse_of: :items, class_name: "Katalyst::Navigation::Menu"
+
+      after_initialize :initialize_tree
+
+      attr_accessor :parent, :children, :index, :depth
+
+      private
+
+      def initialize_tree
+        self.parent   ||= nil
+        self.children ||= []
+      end
+    end
+  end
+end

data/app/models/katalyst/navigation/link.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Navigation
+    # Renders an HTML link using `link_to`.
+    class Link < Item
+      validates :title, :url, presence: true
+    end
+  end
+end