spina-blocks 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bb4bd87c20dc0578090ce0f7e9b26a0ff511f79c52c1e11319527fb9a132362
-  data.tar.gz: 768fbfeb07527abc7d752e7f8af4d51ebd0e86f0e7fc643f313e11d11874de3d
+  metadata.gz: 101db90d52972f83d5d308f7aa1cb1538b722105bba4e45676b520ba805bb438
+  data.tar.gz: cf2d2db9b0eacb4f1a18c2747c317a9da13003df8fa672954bcd3ce2ea75ad84
 SHA512:
-  metadata.gz: 6887a086f16feb25de70d36706ef1f5492c8b3f2831a3e1e7d583b1e62dcf79d547fa9e46edeca27805260a3e68835d9b1234a7144df0a1affd7ef5acf548fbc
-  data.tar.gz: 3741e38abf77005b798a73bdfbfc335f10c7a6109c88551ad6c649f287761714f15aa2e4467e5d65feed3e957c233210da0411e3691dc5204b3b479311dc52a2
+  metadata.gz: ce7bcbb151b613732b0510c9d3f7c356ce161efa33b40df71116d5ebd96f3ab651290fc05408d3d89ad71786efb07c96b3689a40f3734ef54600ac4b530ec35a
+  data.tar.gz: 2c2db687f6312363ecaddf5ab424b24f1ea560d28d7a4ebaadc6817a03e90ed7501952222256139c684da693c41585184be37d53086b4f770c6cf13d1771799c

data/README.md

@@ -1,9 +1,13 @@
 # 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.
 
+## Requirements
+
+- Spina 2.21 or newer. Spina 2.21 builds its admin UI with Tailwind CSS 4, and the plugin's admin views use Tailwind 4 utility names. On Spina 2.20 or older, use spina-blocks 0.4.x.
+
 ## Installation
 
 Add to your Gemfile:
@@ -21,8 +25,16 @@ rails generate spina:blocks:install
 
 This copies the plugin's migrations into your app and runs `db:migrate`.
 
+The plugin registers its views, helpers and JavaScript in `Spina.config.tailwind_content`, so `rails spina:tailwind:build` (also run by `assets:precompile`) picks up the classes it uses in Spina's admin CSS.
+
 ## Upgrading
 
+### To 0.5.0 (Spina 2.21)
+
+Upgrade Spina to 2.21 together with spina-blocks 0.5.0, then rebuild the admin CSS with `rails spina:tailwind:build`. Spina 2.21 needs `tailwindcss-ruby` 4. It generates `app/assets/stylesheets/spina/application.tailwind.css` (with an `@source` line for every `tailwind_content` path) in place of the old `app/assets/config/spina/tailwind.config.js`.
+
+### From timestamp migrations
+
 If you are upgrading from a version that used timestamp migrations (`20250101000001`–`20250101000004`), the new migrations will detect the old version numbers in your `schema_migrations` table, clean them up automatically, and skip any tables that already exist. No manual intervention is needed.
 
 ## Configuration
@@ -72,6 +84,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 = [
     {
@@ -137,6 +155,31 @@ theme.parts = [
 
 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).
 
+#### Filling a reference in inline
+
+A `BlockReference` normally points at a shared block. Pass `inline: true` to also let editors fill the block template's fields in on the page itself, storing that content in the page rather than in a block record:
+
+```ruby
+theme.parts = [
+  { name: "testimonials", title: "Testimonials",
+    part_type: "Spina::Parts::BlockReference",
+    options: { block_template: "testimonials", inline: true } }
+]
+```
+
+The part form then offers two modes: **Select existing** (pick a shared block) and **Fill in here** (page-local content). Both render through the same block template partial, so `render_block(content(:testimonials))` is unchanged and the output is identical either way.
+
+Offering inline mode requires `block_template` — it is the field set editors fill in — and it is not available on parts bound to a `custom_block`. Without `inline: true` the part stays a plain block picker.
+
+Content already stored inline keeps rendering whatever you change later — the gate applies to the editor, not to rendering:
+
+- Remove `inline: true`: the content still shows on the site, and the page editor presents it as read-only rather than offering a block picker that couldn't override it.
+- Remove `block_template` but keep `inline: true`: the content stays editable, because the form falls back to the template it was filled in against.
+
+Either way a save preserves the stored content untouched.
+
+`inline: true` controls what the page editor offers, not what the model accepts; it is an authoring affordance rather than an access control.
+
 Then in your template:
 
 ```erb
@@ -149,6 +192,122 @@ Then in your template:
 <% end %>
 ```
 
+### Yielding content into block templates
+
+`render_block` and `render_custom_block` forward an optional content block to the partial, so block templates can expose `<%= yield %>` slots that callers fill at render time. This lets a single shared block adapt per-page without splitting it into template variants.
+
+In the block partial:
+
+```erb
+<%# app/views/my_theme/blocks/_funnel_form.html.erb %>
+<section class="funnel-form">
+  <% if block_given? %>
+    <%= yield %>
+  <% end %>
+  <%# ...rest of the form... %>
+</section>
+```
+
+In the page that includes it:
+
+```erb
+<%= render_block(content(:funnel_form_block)) do %>
+  <% if (banner = content(:discount_banner_section))&.content(:enabled) %>
+    <%= render "default/shared/blocks/discount_banner", block: banner %>
+  <% end %>
+<% end %>
+```
+
+Pages without anything to inject just call `render_block(...)` without a block — `block_given?` is `false` and the slot stays empty.
+
+## 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                                        |
@@ -162,18 +321,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, &content_block)`   | Render a single block using its template partial; an optional content block is forwarded to the partial via `yield` |
+| `render_custom_block(key, &content_block)` | Render a custom (layout) block by its immutable key; forwards a content block to the partial like `render_block`  |
+| `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,5 +1,6 @@
 import { Controller } from "@hotwired/stimulus";
 import Sortable from "libraries/sortablejs";
+import { positionDropdown } from "spina/utils/dropdown_position";
 
 export default class extends Controller {
   #abortController = null;
@@ -209,7 +210,7 @@ export default class extends Controller {
 
     // Reposition if dropdown is currently visible
     if (this.dropdownTarget.style.display !== "none") {
-      this.#positionDropdown();
+      positionDropdown(this.dropdownTarget);
     }
   }
 
@@ -255,12 +256,12 @@ export default class extends Controller {
   openDropdown() {
     if (this.dropdownTarget.style.display === "block") {
       // Already open, just reposition
-      this.#positionDropdown();
+      positionDropdown(this.dropdownTarget);
       return;
     }
 
     this.dropdownTarget.style.display = "block";
-    this.#positionDropdown();
+    positionDropdown(this.dropdownTarget);
 
     this.#abortController = new AbortController();
     const { signal } = this.#abortController;
@@ -273,7 +274,7 @@ export default class extends Controller {
     let scrollTimeout;
     const debouncedPosition = () => {
       clearTimeout(scrollTimeout);
-      scrollTimeout = setTimeout(() => this.#positionDropdown(), 100);
+      scrollTimeout = setTimeout(() => positionDropdown(this.dropdownTarget), 100);
     };
     window.addEventListener("scroll", debouncedPosition, {
       capture: true,
@@ -297,31 +298,6 @@ export default class extends Controller {
 
   // --- Private ---
 
-  #positionDropdown() {
-    const dropdown = this.dropdownTarget;
-    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";
-    }
-  }
-
   #observeModal() {
     const modalFrame = document.querySelector("turbo-frame[id='modal']");
     if (!modalFrame || !this.hasBlocksDataUrlValue || !this.blocksDataUrlValue)

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

@@ -0,0 +1,55 @@
+import { Controller } from "@hotwired/stimulus";
+
+// Toggles a BlockReference part between "reference" (select a shared block)
+// and "inline" (fill the block template's fields in on the page itself).
+//
+// Styled and driven like Spina's own tabs: active/inactive class lists come
+// from data attributes on the controller element. We don't reuse the `tabs`
+// controller because it always activates the first button on connect, which
+// would misreport the persisted mode.
+export default class extends Controller {
+  static get targets() {
+    return ["button", "referencePane", "inlinePane", "modeField"];
+  }
+
+  connect() {
+    this.#apply(this.hasModeFieldTarget ? this.modeFieldTarget.value : "reference");
+  }
+
+  switch(event) {
+    this.#apply(event.currentTarget.dataset.mode);
+  }
+
+  #apply(mode) {
+    const selected = mode === "inline" ? "inline" : "reference";
+
+    if (this.hasModeFieldTarget) {
+      this.modeFieldTarget.value = selected;
+    }
+
+    this.buttonTargets.forEach((button) => {
+      const isActive = button.dataset.mode === selected;
+      button.classList.remove(...(isActive ? this.#inactiveClasses : this.#activeClasses));
+      button.classList.add(...(isActive ? this.#activeClasses : this.#inactiveClasses));
+    });
+
+    if (this.hasReferencePaneTarget) {
+      this.referencePaneTarget.hidden = selected !== "reference";
+    }
+    if (this.hasInlinePaneTarget) {
+      this.inlinePaneTarget.hidden = selected !== "inline";
+    }
+  }
+
+  get #activeClasses() {
+    return this.#classList("blockReferenceModeActive", "active");
+  }
+
+  get #inactiveClasses() {
+    return this.#classList("blockReferenceModeInactive", "inactive");
+  }
+
+  #classList(datasetKey, fallback) {
+    return (this.element.dataset[datasetKey] || fallback).split(" ").filter(Boolean);
+  }
+}

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"
+  }
+}

data/app/controllers/spina/blocks/admin/blocks_controller.rb

@@ -17,17 +17,19 @@ module Spina
 
           @block_templates = current_theme.try(:block_templates) || []
 
-          if params[:block_template].present?
+          if params[:filter] == "layout"
+            @current_filter = "layout"
+            @blocks = Spina::Blocks::Block.undeletable.sorted
+          elsif params[:block_template].present?
             @current_block_template = params[:block_template]
             @blocks = Spina::Blocks::Block.where(block_template: @current_block_template).sorted
           else
-            @current_block_template = nil
             @blocks = Spina::Blocks::Block.sorted
           end
         end
 
         def new
-          @block_templates = current_theme.try(:block_templates) || []
+          @block_templates = creatable_block_templates
           @block = Spina::Blocks::Block.new(block_template: params[:block_template])
           @modal = params[:modal]
         end
@@ -41,7 +43,7 @@ module Spina
               redirect_to(spina.edit_blocks_admin_block_url(@block))
             end
           else
-            @block_templates = current_theme.try(:block_templates) || []
+            @block_templates = creatable_block_templates
             if params[:modal]
               @modal = true
               render(turbo_stream: turbo_stream.update(
@@ -115,6 +117,12 @@ module Spina
         end
 
         def destroy
+          unless @block.deletable?
+            flash[:error] = I18n.t("spina.blocks.cannot_be_deleted")
+            redirect_to(spina.edit_blocks_admin_block_url(@block))
+            return
+          end
+
           flash[:info] = I18n.t("spina.blocks.deleted")
           @block.destroy
           redirect_to(spina.blocks_admin_blocks_url)
@@ -142,6 +150,16 @@ module Spina
           titles
         end
 
+        # Returns block templates available for manual block creation,
+        # excluding templates reserved for layout (custom) blocks.
+        def creatable_block_templates
+          all_templates = current_theme.try(:block_templates) || []
+          layout_template_names = (current_theme.try(:custom_blocks) || [])
+            .map { |cb| cb[:block_template].to_s }.uniq
+
+          all_templates.reject { |bt| layout_template_names.include?(bt[:name].to_s) }
+        end
+
         def block_params
           params.require(:block).permit!
         end

data/app/controllers/spina/blocks/admin/page_blocks_controller.rb

@@ -32,6 +32,13 @@ module Spina
 
         def destroy
           @page_block = @page.page_blocks.find(params[:id])
+
+          unless @page_block.block.deletable?
+            flash[:error] = I18n.t("spina.page_blocks.cannot_remove_layout_block")
+            redirect_to(spina.blocks_admin_page_page_blocks_url(page_id: @page.id))
+            return
+          end
+
           @page_block.destroy
           flash[:info] = I18n.t("spina.page_blocks.removed")
           redirect_to(spina.blocks_admin_page_page_blocks_url(page_id: @page.id))

data/app/helpers/spina/blocks/blocks_helper.rb

@@ -17,9 +17,13 @@ module Spina
         end
       end
 
-      # Render a single block using its block_template partial
-      # Usage: <%= render_block(some_block) %>
-      def render_block(block)
+      # Render a single block using its block_template partial.
+      # An optional content block is forwarded to the partial, so block
+      # templates can expose `<%= yield %>` slots for callers to inject markup.
+      # Usage:
+      #   <%= render_block(some_block) %>
+      #   <%= render_block(some_block) do %>...<% end %>
+      def render_block(block, &content_block)
         return unless block&.active?
 
         current_spina_theme = Spina::Current.theme || current_theme
@@ -28,7 +32,10 @@ module Spina
         partial_path = "#{theme_name}/blocks/#{block.block_template}"
 
         if lookup_context.exists?(partial_path, [], true)
-          render(partial: partial_path, locals: { block: block })
+          # Use the string-form `render(string, locals, &block)` so passing a
+          # content block doesn't trigger `render`'s implicit layout branch
+          # (which would treat `:partial` as the wrapped content instead).
+          render(partial_path, { block: block }, &content_block)
         else
           render_block_fallback(block)
         end
@@ -45,6 +52,15 @@ module Spina
         block.has_content?(part_name)
       end
 
+      # Render a custom (system) block by its unique key
+      # Usage:
+      #   <%= render_custom_block("header") %>
+      #   <%= render_custom_block("header") do %>...<% end %>
+      def render_custom_block(key, &content_block)
+        block = Spina::Blocks::Block.find_by(key: key)
+        render_block(block, &content_block) if block
+      end
+
       private
 
       def render_block_fallback(block)