spina-blocks 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76633f69018375e8d330eee4b062677dd4dc10bd380ec2e7b08f3900fd448540
-  data.tar.gz: dd386042f84a6554db3eb15200011e4a953f3559054a44f05caa0e052b10fa3b
+  metadata.gz: 24a864994819ca4dd7ee93b0cd6957d008d08586659ad9672654014b2add6961
+  data.tar.gz: 264aca6e16771526496af183ef5443091dc4ae70ea5f550bc0e29f0e9c5d1d5a
 SHA512:
-  metadata.gz: 19b5d1d156f66e85fb34aa6d2240d0f23cd0ffdb973601e2a4a1f3eca8c9058d39332c33bc986b52a69519b7eee22c3e39c6b713c6aadc9ccb5bdb93abaf5e3e
-  data.tar.gz: 7442845e4527e7dcfc8e429771b957638b89c053ae6b20767393756429000908af24337853d5899b9af5d06298efd492f53316a1db91712e85d9321f690647f2
+  metadata.gz: 297624cd733819fbdb489b8a6cfe6a5290959eac521aa11117fbf11aa4b50f999c9b4fccba3c3821e7d16a679b5023943b8bd2470f8a9f114529591a4bdfa899
+  data.tar.gz: 448f9470f24ae571bb6ac2f95aa882bca7b6504c968d5369d591b8e8a1d53711f6fc0d60becb2a793c228e0768b13ab63fc4ea3eb7add2bbf883b864d2fc42af

data/README.md

@@ -1,6 +1,6 @@
 # Spina Blocks
 
-> ⚠️ **Warning**: This plugin is not production-ready and may cause issues. Use at your own risk.
+> **Warning**: This plugin is not production-ready and may cause issues. Use at your own risk.
 
 A plugin for [Spina CMS](https://www.spinacms.com) that adds reusable block components. Blocks are independent content units with their own templates and fields that can be assembled into pages.
 
@@ -72,6 +72,12 @@ Spina::Theme.register do |theme|
     }
   ]
 
+  # Custom blocks (layout blocks, created automatically during bootstrap)
+  theme.custom_blocks = [
+    { name: "header", title: "Header Block", block_template: "header", category: "heroes" },
+    { name: "footer", title: "Footer Block", block_template: "footer", category: "cta" }
+  ]
+
   # Page templates (can use BlockCollection or BlockReference parts)
   theme.view_templates = [
     {
@@ -119,6 +125,24 @@ theme.parts = [
 ]
 ```
 
+#### Filtering blocks by template
+
+By default, `BlockReference` and `BlockCollection` show all active blocks in their selects. To limit the list to blocks of a specific template, pass `block_template` in the part's `options`:
+
+```ruby
+theme.parts = [
+  { name: "hero_block", title: "Hero Block",
+    part_type: "Spina::Parts::BlockReference",
+    options: { block_template: "hero" } },
+
+  { name: "sidebar_blocks", title: "Sidebar Blocks",
+    part_type: "Spina::Parts::BlockCollection",
+    options: { block_template: "sidebar_widget" } }
+]
+```
+
+With this configuration, the "Hero Block" select will only show blocks created with the `hero` template, and "Sidebar Blocks" will only show `sidebar_widget` blocks. If `options` is omitted or does not contain `block_template`, all active blocks are shown (the default behavior).
+
 Then in your template:
 
 ```erb
@@ -131,6 +155,94 @@ Then in your template:
 <% end %>
 ```
 
+## Custom blocks (layout blocks)
+
+Custom blocks are non-deletable blocks that are automatically created during `rake spina:bootstrap`. They work similarly to Spina's `custom_pages` — once defined in the theme configuration, they are created on bootstrap and cannot be deleted through the admin interface. In the admin UI they are labeled as **Layout** blocks.
+
+### Defining custom blocks
+
+Add `custom_blocks` to your theme initializer:
+
+```ruby
+theme.custom_blocks = [
+  { name: "header", title: "Header Block", block_template: "header", category: "heroes" },
+  { name: "footer", title: "Footer Block", block_template: "footer", category: "cta" }
+]
+```
+
+Each custom block accepts:
+
+| Key              | Description                                                              |
+| ---------------- | ------------------------------------------------------------------------ |
+| `name`           | Immutable machine key (used for lookups in code and templates)            |
+| `title`          | (Optional) Initial display name shown in admin. Defaults to `name.titleize`. Editable by users after creation |
+| `block_template` | Must match a template defined in `theme.block_templates`                 |
+| `category`       | (Optional) Name of a category from `theme.block_categories`              |
+
+### Key vs Name
+
+Custom blocks have two identifiers:
+
+- **`key`** — an immutable machine identifier (set from `name` in the config). Used by `render_custom_block`, `BlockReference` with `custom_block` option, and for bootstrap lookups. Cannot be changed after creation. Shown as read-only in the block settings tab.
+- **`name`** — the display name shown in the admin UI. Initially set from `title` (or `name.titleize` if `title` is omitted). Users can freely rename it without breaking any template references.
+
+Regular (non-layout) blocks do not have a `key` — it is `nil` for them.
+
+### How it works
+
+- **Bootstrap**: Custom blocks are created (or updated) automatically whenever `Spina::Account` is saved — this includes `rake spina:bootstrap` and admin account edits. They are created with `deletable: false` and an immutable `key`.
+- **Idempotent**: Running bootstrap multiple times will not duplicate blocks. Existing blocks are found by `key` and updated. The display `name` is only set on initial creation — subsequent bootstraps preserve user edits to the display name.
+- **Deletion protection**: Layout blocks cannot be deleted through the admin UI or programmatically via `destroy`. In the block editor, the `...` menu shows "Block can't be deleted" (matching Spina's page behavior). The controller also rejects delete requests.
+- **Template restriction**: Block templates used by custom blocks are excluded from the "New block" form, preventing users from manually creating blocks with layout templates.
+- **Admin UI**: Layout blocks are marked with a **Layout** badge (right-aligned) in the block library. A **Layout blocks** filter is available in the template filter dropdown. On page block lists, the remove button is replaced with a "Layout" label. The `key` is displayed as read-only in the block settings tab.
+
+### Using custom blocks in templates
+
+#### Direct rendering by key
+
+Use `render_custom_block` to render a system block directly in any template:
+
+```erb
+<%# app/views/my_theme/pages/homepage.html.erb %>
+<%= render_custom_block("header") %>
+
+<main>
+  <%= render_blocks %>
+</main>
+
+<%= render_custom_block("footer") %>
+```
+
+This looks up the block by its immutable `key` and renders it using the block's template partial, just like `render_block`. Renaming the block's display name in the admin will not affect this lookup.
+
+#### As a pre-defined BlockReference
+
+Use the `custom_block` option in a `BlockReference` part to hardcode which block it points to:
+
+```ruby
+theme.parts = [
+  { name: "header_block", title: "Header",
+    part_type: "Spina::Parts::BlockReference",
+    options: { custom_block: "header" } },
+
+  { name: "footer_block", title: "Footer",
+    part_type: "Spina::Parts::BlockReference",
+    options: { custom_block: "footer" } }
+]
+```
+
+When `custom_block` is set:
+- The part's `content` method returns the block by `key` (ignoring `block_id`)
+- In the admin form, instead of a dropdown, a clickable link to the block's edit page is shown
+- If the custom block does not exist yet, a warning message is displayed
+
+Then in your template:
+
+```erb
+<%= render_block(content(:header_block)) %>
+<%= render_block(content(:footer_block)) %>
+```
+
 ## Models
 
 | Model                      | Description                                        |
@@ -144,18 +256,24 @@ Then in your template:
 The plugin adds:
 
 - **Blocks** link in the Content section of the admin sidebar
-- Block library with category tabs for filtering
+- Block library with template filter dropdown
 - Block editor with content fields (same as page editor)
 - Page Blocks management page (per-page block assignment and ordering)
+- **Layout** badge on non-deletable blocks in the block library (right-aligned)
+- **Layout blocks** filter in the template filter dropdown
+- `...` menu shows "Block can't be deleted" for layout blocks (like Spina pages)
+- Block templates used by layout blocks are hidden from the "New block" form
+- Immutable **key** shown as read-only in block settings for layout blocks
 
 ## Helper methods
 
-| Helper                                  | Description                                         |
-| --------------------------------------- | --------------------------------------------------- |
-| `render_blocks(page)`                   | Render all blocks attached to a page via PageBlocks |
-| `render_block(block)`                   | Render a single block using its template partial    |
-| `block_content(block, :part_name)`      | Access a block's content                            |
-| `block_has_content?(block, :part_name)` | Check if a block has content                        |
+| Helper                                  | Description                                            |
+| --------------------------------------- | ------------------------------------------------------ |
+| `render_blocks(page)`                   | Render all blocks attached to a page via PageBlocks    |
+| `render_block(block)`                   | Render a single block using its template partial       |
+| `render_custom_block(key)`              | Render a custom (layout) block by its immutable key    |
+| `block_content(block, :part_name)`      | Access a block's content                               |
+| `block_has_content?(block, :part_name)` | Check if a block has content                           |
 
 ## License
 

data/app/assets/javascripts/spina/controllers/block_collection_controller.js

@@ -1,18 +1,28 @@
 import { Controller } from "@hotwired/stimulus";
 import Sortable from "libraries/sortablejs";
+import { positionDropdown } from "spina/utils/dropdown_position";
 
 export default class extends Controller {
+  #abortController = null;
+  #modalWasOpen = false;
+  #modalObserver = null;
+
+  get #searchQuery() {
+    return this.hasSearchInputTarget ? this.searchInputTarget.value : "";
+  }
+
   static get targets() {
     return [
       "list",
       "hiddenFields",
       "dropdown",
-      "addButton",
+      "searchInput",
       "emptyMessage",
       "listItemTemplate",
       "groupHeaderTemplate",
       "dropdownOptionTemplate",
       "dropdownEmptyTemplate",
+      "newBlockTemplate",
     ];
   }
 
@@ -21,6 +31,8 @@ export default class extends Controller {
       blocks: Array, // [{id, name, templateName, templateTitle}]
       selectedIds: Array, // [id, id, ...]
       editUrl: String, // base edit_modal URL with __ID__ placeholder
+      newUrl: String, // URL for new block modal
+      blocksDataUrl: String, // JSON endpoint to refresh blocks list
     };
   }
 
@@ -36,10 +48,17 @@ export default class extends Controller {
       onEnd: this.reorderHiddenFields.bind(this),
     });
     this.render();
+    this.#observeModal();
   }
 
   disconnect() {
     if (this.sortable) this.sortable.destroy();
+    if (this.#modalObserver) {
+      this.#modalObserver.disconnect();
+      this.#modalObserver = null;
+    }
+    this.#abortController?.abort();
+    this.#abortController = null;
   }
 
   // --- Actions ---
@@ -50,6 +69,9 @@ export default class extends Controller {
     if (this.selectedIdsValue.indexOf(id) !== -1) return;
 
     this.selectedIdsValue = this.selectedIdsValue.concat([id]);
+    if (this.hasSearchInputTarget) {
+      this.searchInputTarget.value = "";
+    }
     this.render();
     this.closeDropdown();
   }
@@ -61,19 +83,23 @@ export default class extends Controller {
     this.render();
   }
 
-  toggleDropdown(event) {
-    event.preventDefault();
-    event.stopPropagation();
-    const dropdown = this.dropdownTarget;
-    if (dropdown.style.display === "none" || dropdown.style.display === "") {
-      this.openDropdown();
-    } else {
-      this.closeDropdown();
-    }
+  onSearchInput() {
+    this.renderDropdown();
+    this.openDropdown();
+  }
+
+  onSearchFocus() {
+    this.renderDropdown();
+    this.openDropdown();
   }
 
   closeOnOutsideClick(event) {
-    if (!this.element.contains(event.target)) {
+    const clickedInsideSearch =
+      this.hasSearchInputTarget &&
+      this.searchInputTarget.contains(event.target);
+    const clickedInsideDropdown = this.dropdownTarget.contains(event.target);
+
+    if (!clickedInsideSearch && !clickedInsideDropdown) {
       this.closeDropdown();
     }
   }
@@ -118,43 +144,74 @@ export default class extends Controller {
   }
 
   renderDropdown() {
-    const availableBlocks = this.blocksValue.filter((b) => {
+    let availableBlocks = this.blocksValue.filter((b) => {
       return this.selectedIdsValue.indexOf(b.id) === -1;
     });
 
+    // Filter by search query
+    const query = this.#searchQuery.toLowerCase().trim();
+    if (query) {
+      availableBlocks = availableBlocks.filter((b) => {
+        return (
+          b.name.toLowerCase().includes(query) ||
+          (b.templateTitle && b.templateTitle.toLowerCase().includes(query)) ||
+          (b.templateName && b.templateName.toLowerCase().includes(query))
+        );
+      });
+    }
+
     this.dropdownTarget.innerHTML = "";
 
     if (availableBlocks.length === 0) {
       const empty = this.dropdownEmptyTemplateTarget.content.cloneNode(true);
       this.dropdownTarget.appendChild(empty);
-      return;
-    }
+    } else {
+      // Group by templateTitle
+      const groups = {};
+      availableBlocks.forEach((b) => {
+        const key = b.templateTitle || b.templateName || "Other";
+        if (!groups[key]) groups[key] = [];
+        groups[key].push(b);
+      });
 
-    // Group by templateTitle
-    const groups = {};
-    availableBlocks.forEach((b) => {
-      const key = b.templateTitle || b.templateName || "Other";
-      if (!groups[key]) groups[key] = [];
-      groups[key].push(b);
-    });
+      Object.keys(groups)
+        .sort()
+        .forEach((groupName) => {
+          const header = this.groupHeaderTemplateTarget.content.cloneNode(true);
+          header.querySelector("[data-role='group-name']").textContent =
+            groupName;
+          this.dropdownTarget.appendChild(header);
 
-    Object.keys(groups)
-      .sort()
-      .forEach((groupName) => {
-        const header = this.groupHeaderTemplateTarget.content.cloneNode(true);
-        header.querySelector("[data-role='group-name']").textContent =
-          groupName;
-        this.dropdownTarget.appendChild(header);
-
-        groups[groupName].forEach((block) => {
-          const option =
-            this.dropdownOptionTemplateTarget.content.cloneNode(true);
-          const button = option.querySelector("button");
-          button.dataset.blockId = block.id;
-          option.querySelector("[data-role='title']").textContent = block.name;
-          this.dropdownTarget.appendChild(option);
+          groups[groupName].forEach((block) => {
+            const option =
+              this.dropdownOptionTemplateTarget.content.cloneNode(true);
+            const button = option.querySelector("button");
+            button.dataset.blockId = block.id;
+            option.querySelector("[data-role='title']").textContent =
+              block.name;
+            this.dropdownTarget.appendChild(option);
+          });
         });
-      });
+    }
+
+    // "New block" link at the bottom of the dropdown
+    if (
+      this.hasNewBlockTemplateTarget &&
+      this.hasNewUrlValue &&
+      this.newUrlValue
+    ) {
+      const newBlock = this.newBlockTemplateTarget.content.cloneNode(true);
+      const link = newBlock.querySelector("[data-role='new-block-link']");
+      if (link) {
+        link.href = this.newUrlValue;
+      }
+      this.dropdownTarget.appendChild(newBlock);
+    }
+
+    // Reposition if dropdown is currently visible
+    if (this.dropdownTarget.style.display !== "none") {
+      positionDropdown(this.dropdownTarget);
+    }
   }
 
   renderEmptyMessage() {
@@ -197,20 +254,76 @@ export default class extends Controller {
   }
 
   openDropdown() {
+    if (this.dropdownTarget.style.display === "block") {
+      // Already open, just reposition
+      positionDropdown(this.dropdownTarget);
+      return;
+    }
+
     this.dropdownTarget.style.display = "block";
-    this._outsideClickHandler = this.closeOnOutsideClick.bind(this);
-    document.addEventListener("click", this._outsideClickHandler, true);
+    positionDropdown(this.dropdownTarget);
+
+    this.#abortController = new AbortController();
+    const { signal } = this.#abortController;
+
+    document.addEventListener("click", (e) => this.closeOnOutsideClick(e), {
+      capture: true,
+      signal,
+    });
+
+    let scrollTimeout;
+    const debouncedPosition = () => {
+      clearTimeout(scrollTimeout);
+      scrollTimeout = setTimeout(() => positionDropdown(this.dropdownTarget), 100);
+    };
+    window.addEventListener("scroll", debouncedPosition, {
+      capture: true,
+      signal,
+    });
+    window.addEventListener("resize", debouncedPosition, { signal });
   }
 
   closeDropdown() {
     this.dropdownTarget.style.display = "none";
-    if (this._outsideClickHandler) {
-      document.removeEventListener("click", this._outsideClickHandler, true);
-      this._outsideClickHandler = null;
+    if (this.hasSearchInputTarget) {
+      this.searchInputTarget.value = "";
     }
+    this.#abortController?.abort();
+    this.#abortController = null;
   }
 
   findBlock(id) {
     return this.blocksValue.find((b) => b.id === id);
   }
+
+  // --- Private ---
+
+  #observeModal() {
+    const modalFrame = document.querySelector("turbo-frame[id='modal']");
+    if (!modalFrame || !this.hasBlocksDataUrlValue || !this.blocksDataUrlValue)
+      return;
+
+    this.#modalWasOpen = false;
+    this.#modalObserver = new MutationObserver(() => {
+      const hasModal = modalFrame.querySelector(".modal");
+      if (hasModal) {
+        this.#modalWasOpen = true;
+      } else if (this.#modalWasOpen) {
+        this.#modalWasOpen = false;
+        this.refreshBlocks();
+      }
+    });
+    this.#modalObserver.observe(modalFrame, { childList: true });
+  }
+
+  refreshBlocks() {
+    fetch(this.blocksDataUrlValue, {
+      headers: { Accept: "application/json" },
+    })
+      .then((response) => response.json())
+      .then((blocks) => {
+        this.blocksValue = blocks;
+        this.render();
+      });
+  }
 }

data/app/assets/javascripts/spina/controllers/content_blocks_controller.js

@@ -0,0 +1,118 @@
+import { Controller } from "@hotwired/stimulus"
+import Sortable from "libraries/sortablejs"
+import { positionDropdown } from "spina/utils/dropdown_position"
+
+// Manages a list of typed content blocks with add, remove, reorder, and collapse.
+//
+// Each block type has a pre-rendered <template> element. When the user adds a
+// block, the template is cloned and the placeholder child_index is replaced
+// with a unique timestamp so Rails form params are unique.
+export default class extends Controller {
+  static targets = [
+    "list",
+    "block",
+    "blockContent",
+    "emptyMessage",
+    "typeMenu",
+    "blockTemplate"
+  ]
+
+  #abortController = null
+
+  connect() {
+    this.sortable = Sortable.create(this.listTarget, {
+      handle: "[data-sortable-handle]",
+      animation: 150
+    })
+    this._updateEmptyMessage()
+  }
+
+  disconnect() {
+    if (this.sortable) this.sortable.destroy()
+    this.#abortController?.abort()
+    this.#abortController = null
+  }
+
+  // --- Actions ---
+
+  addBlock(event) {
+    event.preventDefault()
+    const blockType = event.currentTarget.dataset.blockType
+    const template = this.blockTemplateTargets.find(
+      t => t.dataset.blockType === blockType
+    )
+    if (!template) return
+
+    const childIndex = template.dataset.childIndex
+    const uniqueId = new Date().getTime().toString()
+    const regex = new RegExp(childIndex, "g")
+
+    // Clone template content and replace placeholder child_index
+    const html = template.innerHTML.replace(regex, uniqueId)
+    this.listTarget.insertAdjacentHTML("beforeend", html)
+
+    this._closeTypeMenu()
+    this._updateEmptyMessage()
+  }
+
+  removeBlock(event) {
+    event.preventDefault()
+    if (!confirm("Are you sure you want to remove this block?")) return
+
+    const block = event.currentTarget.closest(`[data-${this.identifier}-target='block']`)
+    if (block) {
+      block.remove()
+      this._updateEmptyMessage()
+    }
+  }
+
+  toggleTypeMenu(event) {
+    event.preventDefault()
+    const menu = this.typeMenuTarget
+    const isOpen = menu.style.display !== "none"
+
+    if (isOpen) {
+      this._closeTypeMenu()
+    } else {
+      menu.style.display = "block"
+      positionDropdown(menu)
+      this.#abortController = new AbortController()
+      const { signal } = this.#abortController
+
+      // Close on outside click (delayed to avoid catching the current click)
+      setTimeout(() => {
+        document.addEventListener("click", (e) => {
+          if (!menu.contains(e.target) && !event.currentTarget.contains(e.target)) {
+            this._closeTypeMenu()
+          }
+        }, { capture: true, once: true, signal })
+      }, 0)
+    }
+  }
+
+  toggleCollapse(event) {
+    event.preventDefault()
+    const block = event.currentTarget.closest(`[data-${this.identifier}-target='block']`)
+    if (!block) return
+
+    const content = block.querySelector(`[data-${this.identifier}-target='blockContent']`)
+    if (content) {
+      content.style.display = content.style.display === "none" ? "" : "none"
+    }
+  }
+
+  // --- Private ---
+
+  _closeTypeMenu() {
+    this.typeMenuTarget.style.display = "none"
+    this.#abortController?.abort()
+    this.#abortController = null
+  }
+
+  _updateEmptyMessage() {
+    if (this.hasEmptyMessageTarget) {
+      const hasBlocks = this.listTarget.children.length > 0
+      this.emptyMessageTarget.style.display = hasBlocks ? "none" : ""
+    }
+  }
+}

data/app/assets/javascripts/spina/controllers/nested_content_blocks_controller.js

@@ -0,0 +1,4 @@
+// Re-exports the content_blocks_controller under the name "nested-content-blocks".
+// This provides Stimulus scope isolation when ContentBlocks are used inside
+// Repeaters or other ContentBlocks containers.
+export { default } from "controllers/content_blocks_controller"

data/app/assets/javascripts/spina/utils/dropdown_position.js

@@ -0,0 +1,30 @@
+// Positions an absolutely-positioned dropdown element above or below its
+// container based on available viewport space.
+//
+// Usage:
+//   import { positionDropdown } from "spina/utils/dropdown_position"
+//   positionDropdown(this.dropdownTarget)
+//
+export function positionDropdown(dropdown) {
+  const container = dropdown.parentElement
+  const containerRect = container.getBoundingClientRect()
+  const dropdownHeight = dropdown.offsetHeight
+  const viewportHeight = window.innerHeight
+
+  const spaceBelow = viewportHeight - containerRect.bottom
+  const spaceAbove = containerRect.top
+
+  if (spaceBelow < dropdownHeight && spaceAbove > spaceBelow) {
+    // Not enough space below and more space above — show above
+    dropdown.style.bottom = "100%"
+    dropdown.style.top = "auto"
+    dropdown.style.marginBottom = "4px"
+    dropdown.style.marginTop = "0"
+  } else {
+    // Default: show below
+    dropdown.style.bottom = "auto"
+    dropdown.style.top = "100%"
+    dropdown.style.marginTop = "4px"
+    dropdown.style.marginBottom = "0"
+  }
+}