[RFC]: Nesting Block

[louisescher]

Summary

Add a new "nesting" block which can act as a grid/flex container for markdown text and other blocks.

Background & Motivation

I work on a lot of sites which have a complex content structure that cannot be expressed by the current "text + content block" format that EmDash uses. Adding a "nested" block to express grids or other containers would solve these issues, for example for grids that a user fills in themselves without me making a single pre-filled component for them to use.

A workflow like that would lead to a lot of back and forth between a developer (or an agent) and the person editing the site every time a component is adjusted, and requires a new deployment to register the component. That, is friction I would like to avoid.

Goals

• Make more dynamic sections possible in EmDash.
• Express structures like flex or grid containers while not having to hard-code them in separate components.

Example

A three-up feature grid the editor fills in themselves. In Portable Text the block is a single node whose children is an ordinary array of blocks:

{
  "_type": "nesting",
  "_key": "n1",
  "layout": "grid",          // "grid" | "flex"
  "columns": 3,              // grid: track count; flex: wrap target
  "gap": "1.5rem",
  "align": "stretch",
  "children": [
    // ...editor adds/removes/reorders freely
  ]
}

Children are the same block types available at the top level (standard text blocks and plugin blocks), so the container is content-type-agnostic. Layout is expressed by a handful of scalar props on the container which the renderer maps them to CSS grid/flex.

Rendered:

---
const { layout, columns, gap, align, children } = resolveNode(Astro.props);
---
<div class:list={["ce-nesting", layout]} style={`--cols:${columns};--gap:${gap};--align:${align}`}>
  {children.map((node) => <PortableText value={[node]} />)}
</div>

Proposed design

Data model

nesting is a custom Portable Text object with:

• scalar layout props (layout, columns, gap, align, optional per-breakpoint overrides), and
• a children array of Portable Text nodes

Editor

Currently, EmDash only produces scalar form fields, which TipTap renders as atom note views, which is fine for storing the data described above, but not for the UI logic required to make this proposal work.

Real in-editor nesting needs a content-holding TipTap node + node view + serializer support:

1. A ProseMirror node spec with content: "block+" (a container that holds other blocks) instead of an atom
2. A node view rendering the drop zone / column chrome around the nested editor region
3. TipTap to/from Portable Text (de)serialization for the children array

@tiptap/extension-table already runs nested-content nodes inside EmDash's editor, so this is already implemented in some way.

Impact on existing systems

A children array is invisible to any code that assumes flat blocks. These need to recurse into children or they will miss the content stored inside it:

• Full-text search
• Media usage tracking
• Seed / content validation
• Visual / inline editing

[ascorbic]

I really like this, and I think it would unlock a lot of use cases. You have identified the biggest potential issue though: the editor. I think this is worth approving for PR, but I think the first steps than anybody should take are some experiments with the editor.

[louisescher]

https://github.com/louisescher/emdash/tree/feat/nesting-block
I've made a test implementation here with the editor. Still bare-bones, but probably good enough for some feedback.

[bimsonz]

@louisescher thanks for putting this up. I rebased it onto 0.31.1 and have been building pages with it. Three things worth raising here rather than in the PR.

The drag handle needs a different unit inside a container, and I am not certain mine is the right answer. With nested targeting on, the default rules resolve the unit inside a structure: for a list, the item. In a page built from containers a list is one row the page is made of, so I replaced them with a rule where a row is a child of the document or a child of a column. That matches what the editor does with nesting off and extends it one level down, so nothing outside a container changes. It also keeps a list movable as a block, which the defaults do not allow anywhere once nested is on. That is the piece I would most like a view on.

The gutter the handle sits in has to belong to the row, not the column. Padding the column leaves it outside every row's box, so a pointer there resolves to the column and the container wins. It reads as the handle jumping away as you reach for it.

Depth is settled. nestingBlock is in group block and a column accepts block+, so containers nest to arbitrary depth. What it cannot express is a page grid with named regions, so a sidebar spanning specific rows is out, the way grid-row: 1 / span 3 would do it. Probably worth stating in the RFC.

One trap for anyone extending the block: the admin carries its own Portable Text converters in PortableTextEditor.tsx, separate from core's. I added an attribute to core only at first. Core's round-trip tests passed and every save dropped it.

Draft PR: #2248

Your prototype commit is its base and stays yours. It is against main rather than your branch only because CI and a review pass do not run otherwise, and it is a draft because I am not trying to land it ahead of you. Say the word and I will move the commits onto your branch and close it.

It adds column width ratios, since equal columns cannot express a content and sidebar page, the drag handling above, and a collapsed state, because a page with a few containers was hard to scan without one.