@emdash-cms/plugin-forms 0.0.1

package/src/schemas.ts

@@ -0,0 +1,215 @@
+/**
+ * Zod schemas for route input validation.
+ */
+
+import { z } from "astro/zod";
+
+/** Matches http(s) scheme at start of URL */
+const HTTP_SCHEME_RE = /^https?:\/\//i;
+
+/** Validates that a URL string uses http or https scheme. Rejects javascript:/data: URI XSS vectors. */
+const httpUrl = z
+	.string()
+	.url()
+	.refine((url) => HTTP_SCHEME_RE.test(url), "URL must use http or https");
+
+// ─── Field Schemas ───────────────────────────────────────────────
+
+const fieldOptionSchema = z.object({
+	label: z.string().min(1),
+	value: z.string().min(1),
+});
+
+const fieldValidationSchema = z
+	.object({
+		minLength: z.number().int().min(0).optional(),
+		maxLength: z.number().int().min(1).optional(),
+		min: z.number().optional(),
+		max: z.number().optional(),
+		pattern: z.string().optional(),
+		patternMessage: z.string().optional(),
+		accept: z.string().optional(),
+		maxFileSize: z.number().int().min(1).optional(),
+	})
+	.optional();
+
+const fieldConditionSchema = z
+	.object({
+		field: z.string().min(1),
+		op: z.enum(["eq", "neq", "filled", "empty"]),
+		value: z.string().optional(),
+	})
+	.optional();
+
+export const fieldTypeSchema = z.enum([
+	"text",
+	"email",
+	"textarea",
+	"number",
+	"tel",
+	"url",
+	"date",
+	"select",
+	"radio",
+	"checkbox",
+	"checkbox-group",
+	"file",
+	"hidden",
+]);
+
+const formFieldSchema = z.object({
+	id: z.string().min(1),
+	type: fieldTypeSchema,
+	label: z.string().min(1),
+	name: z
+		.string()
+		.min(1)
+		.regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/, "Invalid field name"),
+	placeholder: z.string().optional(),
+	helpText: z.string().optional(),
+	required: z.boolean(),
+	validation: fieldValidationSchema,
+	options: z.array(fieldOptionSchema).optional(),
+	defaultValue: z.string().optional(),
+	width: z.enum(["full", "half"]).default("full"),
+	condition: fieldConditionSchema,
+});
+
+const formPageSchema = z.object({
+	title: z.string().optional(),
+	fields: z.array(formFieldSchema).min(1, "Each page must have at least one field"),
+});
+
+// ─── Settings Schema ─────────────────────────────────────────────
+
+const autoresponderSchema = z
+	.object({
+		subject: z.string().min(1),
+		body: z.string().min(1),
+	})
+	.optional();
+
+const formSettingsSchema = z.object({
+	confirmationMessage: z.string().min(1).default("Thank you for your submission."),
+	redirectUrl: httpUrl.optional().or(z.literal("")),
+	notifyEmails: z.array(z.string().email()).default([]),
+	digestEnabled: z.boolean().default(false),
+	digestHour: z.number().int().min(0).max(23).default(9),
+	autoresponder: autoresponderSchema,
+	webhookUrl: httpUrl.optional().or(z.literal("")),
+	retentionDays: z.number().int().min(0).default(0),
+	spamProtection: z.enum(["none", "honeypot", "turnstile"]).default("honeypot"),
+	submitLabel: z.string().min(1).default("Submit"),
+	nextLabel: z.string().optional(),
+	prevLabel: z.string().optional(),
+});
+
+// ─── Form CRUD Schemas ──────────────────────────────────────────
+
+export const formCreateSchema = z.object({
+	name: z.string().min(1).max(200),
+	slug: z
+		.string()
+		.min(1)
+		.max(100)
+		.regex(/^[a-z][a-z0-9-]*$/, "Slug must be lowercase alphanumeric with hyphens"),
+	pages: z.array(formPageSchema).min(1),
+	settings: formSettingsSchema,
+});
+
+export const formUpdateSchema = z.object({
+	id: z.string().min(1),
+	name: z.string().min(1).max(200).optional(),
+	slug: z
+		.string()
+		.min(1)
+		.max(100)
+		.regex(/^[a-z][a-z0-9-]*$/)
+		.optional(),
+	pages: z.array(formPageSchema).min(1).optional(),
+	settings: formSettingsSchema.partial().optional(),
+	status: z.enum(["active", "paused"]).optional(),
+});
+
+export const formDeleteSchema = z.object({
+	id: z.string().min(1),
+	deleteSubmissions: z.boolean().default(true),
+});
+
+export const formDuplicateSchema = z.object({
+	id: z.string().min(1),
+	name: z.string().min(1).max(200).optional(),
+	slug: z
+		.string()
+		.min(1)
+		.max(100)
+		.regex(/^[a-z][a-z0-9-]*$/)
+		.optional(),
+});
+
+export const definitionSchema = z.object({
+	id: z.string().min(1),
+});
+
+export type DefinitionInput = z.infer<typeof definitionSchema>;
+
+// ─── Submission Schemas ──────────────────────────────────────────
+
+export const submitSchema = z.object({
+	formId: z.string().min(1),
+	data: z.record(z.string(), z.unknown()),
+	files: z
+		.record(
+			z.string(),
+			z.object({
+				filename: z.string(),
+				contentType: z.string(),
+				bytes: z.custom<ArrayBuffer>(),
+			}),
+		)
+		.optional(),
+});
+
+export const submissionsListSchema = z.object({
+	formId: z.string().min(1),
+	status: z.enum(["new", "read", "archived"]).optional(),
+	starred: z.boolean().optional(),
+	cursor: z.string().optional(),
+	limit: z.number().int().min(1).max(100).default(50),
+});
+
+export const submissionGetSchema = z.object({
+	id: z.string().min(1),
+});
+
+export const submissionUpdateSchema = z.object({
+	id: z.string().min(1),
+	status: z.enum(["new", "read", "archived"]).optional(),
+	starred: z.boolean().optional(),
+	notes: z.string().optional(),
+});
+
+export const submissionDeleteSchema = z.object({
+	id: z.string().min(1),
+});
+
+export const exportSchema = z.object({
+	formId: z.string().min(1),
+	format: z.enum(["csv", "json"]).default("csv"),
+	status: z.enum(["new", "read", "archived"]).optional(),
+	from: z.string().datetime().optional(),
+	to: z.string().datetime().optional(),
+});
+
+// ─── Type Exports ────────────────────────────────────────────────
+
+export type FormCreateInput = z.infer<typeof formCreateSchema>;
+export type FormUpdateInput = z.infer<typeof formUpdateSchema>;
+export type FormDeleteInput = z.infer<typeof formDeleteSchema>;
+export type FormDuplicateInput = z.infer<typeof formDuplicateSchema>;
+export type SubmitInput = z.infer<typeof submitSchema>;
+export type SubmissionsListInput = z.infer<typeof submissionsListSchema>;
+export type SubmissionGetInput = z.infer<typeof submissionGetSchema>;
+export type SubmissionUpdateInput = z.infer<typeof submissionUpdateSchema>;
+export type SubmissionDeleteInput = z.infer<typeof submissionDeleteSchema>;
+export type ExportInput = z.infer<typeof exportSchema>;

package/src/storage.ts

@@ -0,0 +1,41 @@
+/**
+ * Storage type definition for the forms plugin.
+ *
+ * Declares the two storage collections and their indexes.
+ */
+
+import type { PluginStorageConfig } from "emdash";
+
+export type FormsStorage = PluginStorageConfig & {
+	forms: {
+		indexes: ["status", "createdAt"];
+		uniqueIndexes: ["slug"];
+	};
+	submissions: {
+		indexes: [
+			"formId",
+			"status",
+			"starred",
+			"createdAt",
+			["formId", "createdAt"],
+			["formId", "status"],
+		];
+	};
+};
+
+export const FORMS_STORAGE_CONFIG = {
+	forms: {
+		indexes: ["status", "createdAt"] as const,
+		uniqueIndexes: ["slug"] as const,
+	},
+	submissions: {
+		indexes: [
+			"formId",
+			"status",
+			"starred",
+			"createdAt",
+			["formId", "createdAt"],
+			["formId", "status"],
+		] as const,
+	},
+} satisfies PluginStorageConfig;

package/src/styles/forms.css

@@ -0,0 +1,200 @@
+/**
+ * Optional minimal styles for EmDash forms.
+ *
+ * Uses CSS custom properties for theming.
+ * Import this stylesheet in your site to get basic form styling:
+ *
+ *   import "@emdash-cms/plugin-forms/styles";
+ */
+
+.ec-form {
+	--ec-form-gap: 1rem;
+	--ec-form-field-border: 1px solid #d1d5db;
+	--ec-form-field-radius: 6px;
+	--ec-form-field-padding: 0.5rem 0.75rem;
+	--ec-form-field-bg: #fff;
+	--ec-form-error-color: #dc2626;
+	--ec-form-required-color: #dc2626;
+	--ec-form-help-color: #6b7280;
+	--ec-form-submit-bg: #111827;
+	--ec-form-submit-color: #fff;
+	--ec-form-submit-radius: 6px;
+	--ec-form-submit-padding: 0.625rem 1.25rem;
+
+	display: flex;
+	flex-direction: column;
+	gap: var(--ec-form-gap);
+}
+
+.ec-form-page {
+	display: flex;
+	flex-wrap: wrap;
+	gap: var(--ec-form-gap);
+	border: none;
+	margin: 0;
+	padding: 0;
+}
+
+.ec-form-page-title {
+	width: 100%;
+	font-size: 1.125rem;
+	font-weight: 600;
+	padding: 0;
+	margin-bottom: 0.25rem;
+}
+
+.ec-form-field {
+	display: flex;
+	flex-direction: column;
+	gap: 0.25rem;
+	width: 100%;
+}
+
+.ec-form-field--half {
+	width: calc(50% - var(--ec-form-gap) / 2);
+}
+
+.ec-form-label {
+	font-size: 0.875rem;
+	font-weight: 500;
+}
+
+.ec-form-required {
+	color: var(--ec-form-required-color);
+	margin-left: 0.125rem;
+}
+
+.ec-form-input,
+.ec-form select,
+.ec-form textarea {
+	border: var(--ec-form-field-border);
+	border-radius: var(--ec-form-field-radius);
+	padding: var(--ec-form-field-padding);
+	background: var(--ec-form-field-bg);
+	font: inherit;
+	width: 100%;
+	box-sizing: border-box;
+}
+
+.ec-form-input:focus,
+.ec-form select:focus,
+.ec-form textarea:focus {
+	outline: 2px solid #2563eb;
+	outline-offset: -1px;
+}
+
+.ec-form textarea {
+	min-height: 6rem;
+	resize: vertical;
+}
+
+.ec-form-help {
+	font-size: 0.75rem;
+	color: var(--ec-form-help-color);
+}
+
+.ec-form-error {
+	font-size: 0.75rem;
+	color: var(--ec-form-error-color);
+	min-height: 1em;
+}
+
+.ec-form-error:empty {
+	display: none;
+}
+
+.ec-form-radio-group,
+.ec-form-checkbox-group {
+	display: flex;
+	flex-direction: column;
+	gap: 0.375rem;
+	border: none;
+	padding: 0;
+	margin: 0;
+}
+
+.ec-form-radio-label,
+.ec-form-checkbox-label {
+	display: flex;
+	align-items: center;
+	gap: 0.5rem;
+	font-size: 0.875rem;
+	cursor: pointer;
+}
+
+.ec-form-nav {
+	display: flex;
+	gap: 0.75rem;
+	align-items: center;
+}
+
+.ec-form-submit,
+.ec-form-next {
+	background: var(--ec-form-submit-bg);
+	color: var(--ec-form-submit-color);
+	border: none;
+	border-radius: var(--ec-form-submit-radius);
+	padding: var(--ec-form-submit-padding);
+	font: inherit;
+	font-weight: 500;
+	cursor: pointer;
+}
+
+.ec-form-submit:hover,
+.ec-form-next:hover {
+	opacity: 0.9;
+}
+
+.ec-form-submit:disabled {
+	opacity: 0.6;
+	cursor: not-allowed;
+}
+
+.ec-form-prev {
+	background: transparent;
+	border: var(--ec-form-field-border);
+	border-radius: var(--ec-form-submit-radius);
+	padding: var(--ec-form-submit-padding);
+	font: inherit;
+	font-weight: 500;
+	cursor: pointer;
+}
+
+.ec-form-progress {
+	font-size: 0.875rem;
+	color: var(--ec-form-help-color);
+	text-align: center;
+}
+
+.ec-form-status {
+	padding: 0.75rem;
+	border-radius: var(--ec-form-field-radius);
+	font-size: 0.875rem;
+}
+
+.ec-form-status:empty {
+	display: none;
+}
+
+.ec-form-status--success {
+	background: #f0fdf4;
+	color: #166534;
+	border: 1px solid #bbf7d0;
+}
+
+.ec-form-status--error {
+	background: #fef2f2;
+	color: #991b1b;
+	border: 1px solid #fecaca;
+}
+
+.ec-form-turnstile {
+	margin-top: 0.5rem;
+}
+
+/* Responsive: stack half-width fields on small screens */
+@media (max-width: 640px) {
+	.ec-form-field--half {
+		width: 100%;
+	}
+}

package/src/turnstile.ts

@@ -0,0 +1,51 @@
+/**
+ * Turnstile verification helper.
+ *
+ * Verifies a Turnstile token server-side via the Cloudflare API.
+ */
+
+const VERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+
+export interface TurnstileResult {
+	success: boolean;
+	errorCodes: string[];
+}
+
+/**
+ * Verify a Turnstile response token.
+ *
+ * @param token - The `cf-turnstile-response` token from the client
+ * @param secretKey - The Turnstile secret key
+ * @param httpFetch - The capability-gated fetch function from ctx.http
+ * @param remoteIp - Optional client IP for additional verification
+ */
+export async function verifyTurnstile(
+	token: string,
+	secretKey: string,
+	httpFetch: (url: string, init?: RequestInit) => Promise<Response>,
+	remoteIp?: string | null,
+): Promise<TurnstileResult> {
+	const body: Record<string, string> = {
+		secret: secretKey,
+		response: token,
+	};
+	if (remoteIp) {
+		body.remoteip = remoteIp;
+	}
+
+	const res = await httpFetch(VERIFY_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(body),
+	});
+
+	const data = (await res.json()) as {
+		success: boolean;
+		"error-codes"?: string[];
+	};
+
+	return {
+		success: data.success,
+		errorCodes: data["error-codes"] ?? [],
+	};
+}

package/src/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Core types for the forms plugin.
+ *
+ * These define the data model stored in plugin storage.
+ */
+
+// ─── Form Definitions ────────────────────────────────────────────
+
+export interface FormDefinition {
+	name: string;
+	slug: string;
+	pages: FormPage[];
+	settings: FormSettings;
+	status: "active" | "paused";
+	submissionCount: number;
+	lastSubmissionAt: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface FormPage {
+	/** Page title shown in multi-page progress indicator. Optional for single-page forms. */
+	title?: string;
+	fields: FormField[];
+}
+
+export interface FormSettings {
+	/** Message shown after successful submission */
+	confirmationMessage: string;
+	/** Redirect URL after submission (overrides confirmation message) */
+	redirectUrl?: string;
+	/** Email addresses for submission notifications */
+	notifyEmails: string[];
+	/** Enable daily digest instead of per-submission notifications */
+	digestEnabled: boolean;
+	/** Hour (0-23) to send digest, in site timezone */
+	digestHour: number;
+	/** Autoresponder email sent to the submitter */
+	autoresponder?: {
+		subject: string;
+		body: string;
+	};
+	/** Webhook URL for submission notifications */
+	webhookUrl?: string;
+	/** Days to retain submissions (0 = forever) */
+	retentionDays: number;
+	/** Spam protection strategy */
+	spamProtection: "none" | "honeypot" | "turnstile";
+	/** Submit button text */
+	submitLabel: string;
+	/** Label for Next button on multi-page forms */
+	nextLabel?: string;
+	/** Label for Previous button on multi-page forms */
+	prevLabel?: string;
+}
+
+// ─── Form Fields ─────────────────────────────────────────────────
+
+export interface FormField {
+	id: string;
+	type: FieldType;
+	label: string;
+	/** HTML input name, unique per form */
+	name: string;
+	placeholder?: string;
+	helpText?: string;
+	required: boolean;
+	validation?: FieldValidation;
+	/** For select, radio, checkbox-group */
+	options?: FieldOption[];
+	defaultValue?: string;
+	/** Layout hint */
+	width: "full" | "half";
+	/** Conditional visibility */
+	condition?: FieldCondition;
+}
+
+export type FieldType =
+	| "text"
+	| "email"
+	| "textarea"
+	| "number"
+	| "tel"
+	| "url"
+	| "date"
+	| "select"
+	| "radio"
+	| "checkbox"
+	| "checkbox-group"
+	| "file"
+	| "hidden";
+
+export interface FieldValidation {
+	minLength?: number;
+	maxLength?: number;
+	min?: number;
+	max?: number;
+	/** Regex pattern */
+	pattern?: string;
+	/** Error message for pattern mismatch */
+	patternMessage?: string;
+	/** File types, e.g. ".pdf,.doc" */
+	accept?: string;
+	/** Max file size in bytes */
+	maxFileSize?: number;
+}
+
+export interface FieldOption {
+	label: string;
+	value: string;
+}
+
+export interface FieldCondition {
+	/** Name of the controlling field */
+	field: string;
+	op: "eq" | "neq" | "filled" | "empty";
+	value?: string;
+}
+
+// ─── Submissions ─────────────────────────────────────────────────
+
+export interface Submission {
+	formId: string;
+	data: Record<string, unknown>;
+	files?: SubmissionFile[];
+	status: "new" | "read" | "archived";
+	starred: boolean;
+	notes?: string;
+	createdAt: string;
+	meta: SubmissionMeta;
+}
+
+export interface SubmissionFile {
+	fieldName: string;
+	filename: string;
+	contentType: string;
+	size: number;
+	/** Reference to media library item */
+	mediaId: string;
+}
+
+export interface SubmissionMeta {
+	ip: string | null;
+	userAgent: string | null;
+	referer: string | null;
+	country: string | null;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────
+
+/** Get all fields across all pages */
+export function getFormFields(form: FormDefinition): FormField[] {
+	return form.pages.flatMap((p) => p.fields);
+}
+
+/** Check if a form has multiple pages */
+export function isMultiPage(form: FormDefinition): boolean {
+	return form.pages.length > 1;
+}
+
+/** Check if a form has any file fields */
+export function hasFileFields(form: FormDefinition): boolean {
+	return getFormFields(form).some((f) => f.type === "file");
+}