Field Kit

El tipo de campo json de EmDash almacena datos estructurados arbitrarios, pero el editor predeterminado es una entrada de texto de una sola línea donde debe escribir JSON sin formato a mano. Field Kit es un plugin de primera parte que incluye cuatro widgets componibles para campos json, configurados completamente mediante options de seed — sin necesidad de React para los creadores de sitios.

Instalación

npm i @emdash-cms/plugin-field-kit

Registre el plugin en astro.config.mjs:

import { defineConfig } from "astro/config";
import emdash from "emdash";
import { fieldKitPlugin } from "@emdash-cms/plugin-field-kit";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [fieldKitPlugin()],
		}),
	],
});

Luego adjunte un widget a cualquier campo json configurando widget como field-kit:<name>:

{
	"slug": "ingredients",
	"type": "json",
	"widget": "field-kit:list",
	"options": { "fields": [...] }
}

Widgets

Si a un widget le faltan sus options requeridas (por ejemplo, fields para object-form/list, o rows/columns para grid), el editor muestra una advertencia en línea “Widget mal configurado” en lugar de una entrada rota — útil mientras se itera en esquemas de seed.

object-form

Renderiza un grupo de subcampos tipados que se almacenan como un solo objeto JSON. Bueno para datos estructurados de forma fija como datos nutricionales o información de contacto.

{
	"slug": "nutrition",
	"type": "json",
	"widget": "field-kit:object-form",
	"options": {
		"collapsed": false,
		"fields": [
			{ "key": "calories", "label": "Calories", "type": "number", "suffix": "kcal" },
			{ "key": "protein", "label": "Protein", "type": "number", "suffix": "g" },
			{ "key": "fat", "label": "Fat", "type": "number", "suffix": "g" },
			{ "key": "carbs", "label": "Carbs", "type": "number", "suffix": "g" }
		]
	}
}

Valor almacenado: { "calories": 250, "protein": 12.5, "fat": 8, "carbs": 30 }.

list

Un editor de array ordenado con controles de agregar, eliminar y reordenar. Cada fila es un objeto JSON cuya forma está definida por fields. El encabezado de la fila muestra un resumen renderizado desde una plantilla tipo Mustache.

{
	"slug": "ingredients",
	"type": "json",
	"widget": "field-kit:list",
	"options": {
		"itemLabel": "Ingredient",
		"min": 1,
		"max": 50,
		"sortable": true,
		"summary": "{{name}} — {{amount}}",
		"fields": [
			{ "key": "name", "label": "Name", "type": "text", "required": true },
			{ "key": "amount", "label": "Amount", "type": "text" },
			{ "key": "optional", "label": "Optional", "type": "boolean" }
		]
	}
}

Valor almacenado:

[
	{ "name": "Flour", "amount": "500g", "optional": false },
	{ "name": "Butter", "amount": "200g", "optional": false }
]

grid

Una matriz bidimensional de filas × columnas. Cada celda puede ser un interruptor, entrada de texto, entrada numérica o selección. Útil para matrices como disponibilidad estacional, tablas de precios o comparaciones de características.

{
	"slug": "availability",
	"type": "json",
	"widget": "field-kit:grid",
	"options": {
		"cell": "toggle",
		"rows": [
			{ "key": "berries", "label": "Berries" },
			{ "key": "stoneFruit", "label": "Stone fruit" },
			{ "key": "citrus", "label": "Citrus" }
		],
		"columns": [
			{ "key": "spring", "label": "Spring" },
			{ "key": "summer", "label": "Summer" },
			{ "key": "autumn", "label": "Autumn" },
			{ "key": "winter", "label": "Winter" }
		]
	}
}

Valor almacenado:

{
	"berries": { "spring": false, "summer": true, "autumn": false, "winter": false },
	"stoneFruit": { "spring": false, "summer": true, "autumn": true, "winter": false },
	"citrus": { "spring": false, "summer": false, "autumn": true, "winter": true }
}

tags

Una entrada tipo chip para arrays de strings. Admite una lista fija de suggestions, valores personalizados de forma libre (conmutable), transformaciones de mayúsculas/minúsculas y un max opcional.

{
	"slug": "keywords",
	"type": "json",
	"widget": "field-kit:tags",
	"options": {
		"placeholder": "Add a keyword…",
		"max": 10,
		"transform": "lowercase",
		"allowCustom": true,
		"suggestions": ["vegan", "vegetarian", "gluten-free", "dairy-free", "nut-free"]
	}
}

Valor almacenado: ["vegan", "gluten-free"].

Presione Enter o , para confirmar una etiqueta. Backspace en una entrada vacía elimina la última etiqueta. Las etiquetas duplicadas se ignoran silenciosamente.

Subcampos

object-form y list aceptan un array options.fields de definiciones de subcampos tipados. Cada entrada tiene una key (la clave del objeto JSON en la que escribe), un label, un type y extras específicos del tipo.

Props comunes en cada subcampo: required, helpText, defaultValue.

Plantillas de resumen

El widget list renderiza cada fila colapsada usando una plantilla tipo Mustache en options.summary. {{key}} se reemplaza con el valor de la fila para esa clave (convertido a string). Los valores falsy vuelven a "{itemLabel} {n}".

"summary": "{{name}} — {{amount}}"

Renderiza filas como Flour — 500g. La plantilla es una sustitución de string simple — sin HTML, sin expresiones anidadas.

Durabilidad de datos

Los widgets de Field Kit almacenan JSON simple en la columna existente del campo. No hay tablas específicas del plugin, ni claves foráneas, ni mutación de esquema. Si elimina @emdash-cms/plugin-field-kit de su configuración, los datos permanecen válidos — solo la UI de edición vuelve a la entrada de texto json predeterminada.

Esto se aplica incluso cuando cambia la forma del widget: las claves desconocidas en los objetos almacenados se conservan en la próxima escritura, por lo que puede evolucionar un esquema sin perder datos capturados bajo un conjunto de campos más antiguo.

Ver también

• Descripción general de plugins — cómo funcionan los plugins de EmDash.
• Elegir un formato de plugin — escriba sus propios widgets de campo si Field Kit no se ajusta.
• Discussion #571 — la propuesta que llevó a este plugin.