Add collapsible sections, shared includes, copy/paste, perf cache, and recently-used blocks

[helmutkaufmann]

Summary

This PR adds several independent editor and developer-experience improvements to the Blocks plugin.

Collapsible sections

• type: section fields support collapsible: true shorthand, with collapsed: true|false controlling the initial state.
• Open/closed state persists across page reloads via localStorage (keyed by field name).
• Implemented via a data-block-collapsible attribute bootstrapped inline in the block widget partial, independent of core's collapsible-section JS. This is intentional: core re-collapses and re-binds every section on each form-widget init (including when a nested repeater adds an item), which broke manually-opened sections and stalled repeater "Add item" clicks.

Shared field includes

• Block definitions may declare a top-level include: (string or list) to merge fields and config from external plain-YAML files.
• Included definitions form the base; the block's own definitions override on key collision.
• Nested includes are resolved recursively, guarded against circular references.
• Missing include files are skipped and logged as a warning.
• A schema guard logs a warning when an include would redefine a field with a different type.

Recently used blocks

• The most-recently used block types are pinned to the top of the "Add block" palette, tracked per browser in localStorage.

Copy / Cut / Paste / Duplicate blocks

• Each block item has a single horizontal toolbar: collapse, copy, cut, paste, duplicate, (config if applicable), delete.
• Server-side copy/paste: copying calls onCopyItem, which builds the block's form widget server-side and calls getSaveData(). This correctly captures every field type — switches, mediafinders, nested repeaters with their own rows — which a client-side DOM scrape cannot.
• Paste inserts the new block immediately after the target, or via a "Paste block" entry in the + Add New Item palette (useful for empty widgets).
• Paste and duplicate respect the widget's allow / ignore / tags constraints.
• Clipboard persists for the browser session (sessionStorage).

Performance: cross-request config cache

• BlockManager::getConfigs() now stores built block configs in the Laravel cache, keyed by an md5 signature of every block file's mtime.
• On warm requests the full config build (~17–97ms for ~100 blocks) is replaced by a cheap mtime check (~0.1ms).
• Cache self-invalidates when any .block file or included YAML file changes — no manual cache:clear needed.
• A per-request in-memory memo prevents even the mtime check from running more than once per request.

Tests

• BlockManagerTest: include merging, block-overrides-include precedence, nested includes, circular-include guard, missing-file skip, multiple includes, and the no-include no-op.
• BlocksTest: collapsible/collapsed shorthand translation, and that non-section / plain-section fields are left untouched.
• Fixtures under tests/fixtures/blocks/includes/.

Test plan

• Add a collapsible: true section to a block, confirm it collapses/expands and state survives a page reload
• Define a shared _shared.yaml include and confirm fields merge correctly (block fields override)
• Copy a gallery block (with mediafinder + switch + nested repeater rows) and paste it — confirm all content is reproduced
• Duplicate a block and confirm the clone appears immediately after
• Paste affordances should only appear for block types allowed by the target widget's allow/ignore/tags
• Edit a .block file and confirm the config cache invalidates (no stale data)
• Run php artisan test --filter=BlockManagerTest and php artisan test --filter=BlocksTest

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Collapsible block sections with persisted open/closed state
  • Shared block field includes with recursive resolution, collision rules, and circular-reference protection
  • “Recently used” blocks pinned in the Add Block palette
  • Improved clipboard actions (copy/cut/paste/duplicate) that preserve complex nested block data
  • Cross-request block configuration caching for faster block setup
• Documentation
  • Expanded README with end-to-end YAML/Twig examples and detailed feature guidance
• Chores
  • Added .DS_Store to ignore rules and clarified build runtime separation for blocks.js files

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 250dff5b-5065-4260-83f8-e69dfbf2c0f3

📥 Commits

Reviewing files that changed from the base of the PR and between 394a016 and f907876.

📒 Files selected for processing (5)

• classes/BlockManager.php
• formwidgets/Blocks.php
• formwidgets/blocks/assets/less/blocks.less
• formwidgets/blocks/partials/_block.php
• updates/version.yaml

💤 Files with no reviewable changes (1)

• updates/version.yaml

🚧 Files skipped from review as they are similar to previous changes (4)

• formwidgets/blocks/assets/less/blocks.less
• formwidgets/Blocks.php
• formwidgets/blocks/partials/_block.php
• classes/BlockManager.php

---

Walkthrough

This PR introduces several interrelated features to the WinterCMS blocks plugin. BlockManager gains recursive YAML include: resolution with cycle detection, merge/override semantics, type-collision warnings, and a two-tier config cache (per-request memoization + cross-request Laravel cache keyed by block-file mtimes). Blocks.php adds a normalizeBlockFields() method translating collapsible/collapsed YAML shorthands into data-block-collapsible container attributes, plus onCopyItem() and a reworked onAddItem() that seed paste data server-side via getSaveData(). The _block_item.php partial consolidates item controls into a unified toolbar; a large inline JavaScript IIFE in _block.php implements clipboard management, collapsible section state persistence, recently used block palette reordering, and paste insertion. Tests cover include resolution and collapsible normalization. Documentation, version, and housekeeping files are also updated.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the five main features added: collapsible sections, shared includes, copy/paste functionality, performance caching, and recently-used blocks tracking.
Docstring Coverage	✅ Passed	Docstring coverage is 81.25% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch main

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[LukeTowers]

@helmutkaufmann can you add screenshots for the changes you've made? Claude is really good at using playwright to generate those for you FYI. Ideal if able to provide before / afters to make it easier to review such a large PR.

[helmutkaufmann]

Yes, I can

[coderabbitai]

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

CHANGELOG.md (1)

1-70: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Document the "Tabs and secondaryTabs support" feature or remove it from version.yaml.

The version.yaml file (line 5) lists "Tabs and secondaryTabs support in block definitions" as part of the 1.1.0 release, but this feature is not documented anywhere in the CHANGELOG.md Unreleased section. The PR objectives also do not mention this feature—only five features are listed (collapsible sections, shared field includes, recently used blocks, copy/paste/duplicate blocks, and performance cache). Ensure consistency between version.yaml and CHANGELOG.md: either add documentation for tabs/secondaryTabs to the CHANGELOG, or remove this item from version.yaml if it is not part of this release.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CHANGELOG.md` around lines 1 - 70, The version.yaml file lists "Tabs and
secondaryTabs support in block definitions" as part of the 1.1.0 release, but
this feature is not documented in the CHANGELOG.md Unreleased section. To fix
this inconsistency, either add documentation for the tabs/secondaryTabs feature
to the CHANGELOG.md Unreleased section (following the same format and structure
as the other features like collapsible sections, shared field includes, etc.),
or remove the tabs/secondaryTabs line from version.yaml if this feature is not
actually part of this release. Ensure both files are consistent about what
features are included in this version.

🧹 Nitpick comments (1)

tests/classes/BlockManagerTest.php (1)

149-167: ⚡ Quick win

Add a collision-precedence assertion for multi-include order.

testMultipleIncludes() currently checks only presence. It should also assert which include wins on field-key collisions, so ordering regressions are caught.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/classes/BlockManagerTest.php` around lines 149 - 167, The
testMultipleIncludes method in BlockManagerTest.php currently only verifies that
fields from multiple includes are present, but does not test
collision-precedence (which include wins when field keys overlap). Add an
assertion to check the actual content or properties of a field that exists in
both _base.yaml and _shared.yaml to verify that the correct include takes
precedence based on the order specified in the include array. This ensures that
changes to the include-merging order are caught as regressions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@classes/BlockManager.php`:
- Around line 292-296: The issue is that when an included file cannot be found
or symbolized in the BlockManager class, it is skipped without being recorded in
the $touchedIncludes tracking mechanism. This causes includesUnchanged() to
incorrectly report unchanged includes when a previously missing file is later
created. To fix this, ensure that the $path (or $realPath if available) is added
to $touchedIncludes even when File::exists($realPath) returns false or when
symbolizePath fails. This way, the cache metadata will properly track missing
files and invalidate when they are subsequently created. Apply the same fix to
both the first occurrence at lines 292-296 and the second occurrence at lines
304-307 where similar file existence checks occur.
- Around line 321-327: The issue is that `$own` is being extracted from the
already-merged `$config` array, causing earlier includes to take precedence over
later ones instead of following list-order precedence. To fix this in the
BlockManager.php code block around the warnOnTypeCollisions method call, obtain
`$own` from the raw, original block configuration before any merging occurs,
rather than from the current state of `$config`. This ensures that later
includes in the list can properly override earlier includes when collisions
happen, maintaining correct precedence order.

In `@formwidgets/Blocks.php`:
- Around line 201-206: In the onCopyItem() method in formwidgets/Blocks.php, add
a call to $this->prepareVars() before the existing call to makeItemFormWidget()
to ensure that $groupDefinitions is properly populated. This is necessary
because makeItemFormWidget() requires the group definitions to correctly build
the form widget with the proper schema for the specified group code, and without
calling prepareVars() first, the copy operation may fail or use incorrect field
schemas. Follow the same pattern used in onAddItem() and render() methods which
both call prepareVars() before working with form widgets.

In `@formwidgets/blocks/assets/less/blocks.less`:
- Around line 64-68: The `.transform(rotate(180deg));` LESS mixin call in the
collapsed repeater item rule is not recognized by Stylelint and causes linting
errors. Replace the mixin call with the standard CSS transform property syntax:
change `.transform(rotate(180deg));` to `transform: rotate(180deg);` within the
`.field-block-item.collapsed > .repeater-item-remove
.repeater-item-collapse-one` selector block.

In `@formwidgets/blocks/partials/_block.php`:
- Around line 386-389: The storageKey function is generating persistence keys
using only the data-field-name attribute, which causes sections with identical
field names in different block groups or widgets to share the same storage key
and overwrite each other's collapsed state. Modify the storageKey function to
include additional context that uniquely identifies the block or widget
containing the section (such as a parent block identifier, widget reference, or
other distinguishing attribute) alongside the field name when constructing the
COLLAPSE_PREFIX key. This will ensure each section's collapsed state is stored
independently based on both its field name and its containing context.

---

Outside diff comments:
In `@CHANGELOG.md`:
- Around line 1-70: The version.yaml file lists "Tabs and secondaryTabs support
in block definitions" as part of the 1.1.0 release, but this feature is not
documented in the CHANGELOG.md Unreleased section. To fix this inconsistency,
either add documentation for the tabs/secondaryTabs feature to the CHANGELOG.md
Unreleased section (following the same format and structure as the other
features like collapsible sections, shared field includes, etc.), or remove the
tabs/secondaryTabs line from version.yaml if this feature is not actually part
of this release. Ensure both files are consistent about what features are
included in this version.

---

Nitpick comments:
In `@tests/classes/BlockManagerTest.php`:
- Around line 149-167: The testMultipleIncludes method in BlockManagerTest.php
currently only verifies that fields from multiple includes are present, but does
not test collision-precedence (which include wins when field keys overlap). Add
an assertion to check the actual content or properties of a field that exists in
both _base.yaml and _shared.yaml to verify that the correct include takes
precedence based on the order specified in the include array. This ensures that
changes to the include-merging order are caught as regressions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c5771813-68f9-43c2-94e1-c236e72dbb86

📥 Commits

Reviewing files that changed from the base of the PR and between 6a824f9 and 394a016.

📒 Files selected for processing (18)

• .gitignore
• CHANGELOG.md
• README.md
• classes/BlockManager.php
• composer.json
• formwidgets/Blocks.php
• formwidgets/blocks/assets/less/blocks.less
• formwidgets/blocks/partials/_block.php
• formwidgets/blocks/partials/_block_item.php
• tests/classes/BlockManagerTest.php
• tests/fixtures/blocks/includes/_base.yaml
• tests/fixtures/blocks/includes/_cycle_a.yaml
• tests/fixtures/blocks/includes/_cycle_b.yaml
• tests/fixtures/blocks/includes/_shared.yaml
• tests/fixtures/blocks/includes/_with_nested.yaml
• tests/formwidgets/BlocksTest.php
• updates/version.yaml
• winter.mix.js

[helmutkaufmann]

Copy/Paste/Duplicate (top right in the Gallery exampe block) icons to copy the existing block with any nested blocks inside

---

When a block is in the clipboard, it can directly pasted when adding a new block to a repeater

[helmutkaufmann]

@LukeTowers: These are the only visible changes. Note that the Gallery block, when adding a new block to the repeater, has moved to the front as it has been recently used.

And apologies for the big PR. I will do better next time. Think though that these are some good extensions to the plugin.

[LukeTowers]

@helmutkaufmann can you fix the merge conflict?