Bento grid field widget for EmDash JSON fields.
@bnomei/emdash-bento is a native EmDash plugin for row and
column layout data stored as plain JSON. It registers the bento:layouts
admin widget, reuses @bnomei/emdash-blocks for nested column content,
and exports helpers for Astro renderers to prepare visible rows and translate
fractional spans into a 12-column grid. Use it when editors need controlled
layout composition while templates still own the frontend markup.
- Native EmDash plugin factory:
bentoPlugin(). - JSON field widget:
bento:layouts. - One editable layout pattern string per row.
- Nested block controls through
options.blockDefinitions. - Admin UI built with Kumo UI with full light and dark mode support.
- Frontend helpers:
visibleLayoutRows()andspanToGridColumns().
npm install @bnomei/emdash-bento @bnomei/emdash-blocksRegister both plugins in astro.config.mjs:
import emdash from "emdash/astro";
import { bentoPlugin } from "@bnomei/emdash-bento";
import { blockBuilderPlugin } from "@bnomei/emdash-blocks";
export default {
integrations: [
emdash({
plugins: [blockBuilderPlugin(), bentoPlugin()],
}),
],
};Use the widget on an EmDash json field:
{
"slug": "layouts",
"label": "Grid",
"type": "json",
"widget": "bento:layouts",
"options": {
"blockDefinitions": [
{
"type": "heading",
"label": "Heading",
"props": [{ "key": "text", "label": "Text", "type": "text" }]
},
{
"type": "text",
"label": "Text",
"props": [{ "key": "text", "label": "Text", "type": "markdown" }]
},
{
"type": "image",
"label": "Image",
"props": [{ "key": "image", "label": "Image", "type": "media" }]
}
]
}
}type LayoutBuilderValue = Array<{
id: string;
layout: string;
settings?: Record<string, unknown>;
columns: Array<{
id: string;
span: string;
blocks: BlockBuilderValue;
}>;
}>;Empty layout fields stay empty when the admin widget mounts, so opening an untouched entry does not write a default row or mark the field dirty. The widget shows an empty state with the Add Layout button, and clicking that button creates the first editable row.
Each row stores exactly one layout pattern. The pattern is a comma-separated
list of column spans, for example 1/1, 1/2, 1/2, or 1/1, 1/3, 2/3.
Editing the pattern updates the row's columns by position, preserving existing
column blocks where a matching column index still exists. If the edited pattern
has fewer spans than the row already has columns, columns beyond that pattern
are removed. The per-column span values mirror the row pattern and are stored
so frontend renderers can read the same data directly.
Editors can also append a column with the row-level Add Column button. New
columns start as 1/1, and the row pattern updates to match the visible
columns.
The Add Layout button creates a new row with 1/1, 1/2, 1/3; editors can
change that row's layout pattern after it has been added.
Each column header also exposes a sorted width select and a remove button. The select choices are the unique spans in that row's current layout pattern. Layouts can be reordered with up/down controls. Columns can be reordered with left/right controls.
The admin widget renders columns on a 12-column CSS grid where 1/2 spans 6 grid columns and 1/3 spans 4 columns. If a row's widths add up to more than 1/1, the extra columns wrap to the next line. The widget accepts comma-separated fractions with denominators up to twelfths, so editors can type one row pattern such as 1/1, 1/2, 1/2, or 1/1, 2/3, 1/3 and override it whenever the layout needs to change.
Nested blocks use @bnomei/emdash-blocks directly. Pass
options.blockDefinitions to control the available nested block types and their
typed prop controls. Standalone block fields and layout column blocks share the
same definition shape.
Render layout rows as a 12-column CSS grid. The package exports helpers for the common data preparation and span calculation:
import { layoutGridSpans, visibleLayoutRows } from "@bnomei/emdash-bento";
import { visibleBlocks } from "@bnomei/emdash-blocks";
const rows = visibleLayoutRows(entry.layouts);{
rows.map((row) => {
const gridSpans = layoutGridSpans(row.columns.map((column) => column.span));
return (
<section class="layout" data-layout-id={row.id}>
{row.columns.map((column, columnIndex) => (
<div
class="column"
style={`--span: ${gridSpans[columnIndex] ?? 12}`}
data-column-id={column.id}
>
{visibleBlocks(column.blocks).map((block) => renderBlock(block))}
</div>
))}
</section>
);
})
}.layout {
display: grid;
grid-template-columns: repeat(12, minmax(0, 1fr));
}
.column {
grid-column: span var(--span) / span var(--span);
}The helpers accept native Bento values. Migration from other systems should happen before values are saved into EmDash.
- ESM entry:
@bnomei/emdash-bento. - Admin entry:
@bnomei/emdash-bento/admin. - Type declarations are included from
dist/. - Peer dependencies:
@bnomei/emdash-blocks^0.2.1,emdash^1.2.0,react^18.0.0 || ^19.0.0,react-dom^18.0.0 || ^19.0.0,@cloudflare/kumo2.6.0, and@phosphor-icons/react^2.1.10.
Kumo matches the version used to compile EmDash 1.2's admin stylesheet. Upgrading Kumo independently can leave component classes missing from that stylesheet.
Use Node.js 22.18+ (22.x), 24.11+ (24.x), or 26+ for the Vite+ toolchain.
npm ci
npx playwright install --with-deps chromium
npm run check
npm run typecheck
npm test
npm run pack:check
npm run types:check
npm pack --dry-runnpm test runs unit/registration tests and Playwright Chromium tests against the
built admin entry, real Blocks/Kumo components, and EmDash 1.2's published admin
CSS. Browser checks cover clean empty mounts, row and column operations, invalid
layout drafts, nested block editing, locale changes, and fractional grid geometry.
Light/dark screenshots capture empty and populated fields, the open width
menu, and a narrow localized empty state for manual review. This is a controlled widget fixture,
not a full CMS login, database-save, or media-upload end-to-end test.
Use npm run test:unit or npm run test:browser for focused runs. Screenshots
are generated at 2x scale under ignored test-results/; they are review evidence,
not committed baselines or automatic pixel comparisons. CI failures retain
screenshots and traces in the browser-results artifact. Tests, fixtures,
Playwright configuration, and generated reports are excluded from the npm package
by the files allowlist. The existing public screenshot.png is unchanged.
Before publishing 0.3.0, date its changelog entry and publish a matching v0.3.0
GitHub release. The existing release workflow tests and publishes to npm; preparing
the version locally does not publish it.
This package ships as a native EmDash plugin because the editor is a trusted React admin field widget. Package exports point at Viteplus vp pack-built dist/ JavaScript and declarations; use npm run build for the production pack and npm run pack:check for the publint-verified pack check.
@bnomei/emdash-blocksprovides the nested block editor used by Bento columns.@bnomei/emdash-fieldsprovides smaller JSON-backed field widgets.
MIT.
