@c9up/station 0.1.5 → 0.1.7

package/src/index.ts

@@ -1,8 +1,18 @@
 export { kebabCase, pluralise, titleCase } from "./casing.js";
 export { defineResource } from "./defineResource.js";
 export { ResourceRegistry } from "./ResourceRegistry.js";
-export type { StationAppContext } from "./StationProvider.js";
+export type { StationAppContext, StationConfig } from "./StationProvider.js";
 export { default as StationProvider } from "./StationProvider.js";
+
+import type { StationConfig } from "./StationProvider.js";
+
+/**
+ * Author-time config helper for `config/station.ts` — AdonisJS `defineConfig`
+ * parity. Identity at runtime; the generic preserves literal types for inference.
+ */
+export function defineConfig<T extends StationConfig>(config: T): T {
+	return config;
+}
 export {
 	type AuditEvent,
 	type AuditSink,

package/src/views/form.ts

@@ -2,23 +2,24 @@
  * `GET /admin/<slug>/new` + `GET /admin/<slug>/:id/edit` — form view
  * shared between the create and edit actions (Story 54.3).
  *
- * Field rendering is INFERRED from the entity's `@Column` metadata
- * (Story 54.5): column type maps to an `<input type>`, boolean →
- * checkbox, text-long → textarea, etc. The primary key and any
- * timestamp columns (`created_at` / `updated_at` / `deleted_at`) are
- * skipped from the form body. Per-field overrides declared on
+ * Pure `(input) => FormViewModel` builder (Story 57.3). Field rendering is
+ * INFERRED from the entity's `@Column` metadata (Story 54.5): column type maps
+ * to an `<input type>`, boolean → checkbox, text-long → textarea, etc. The
+ * primary key plus the timestamp columns (`created_at` / `updated_at` /
+ * `deleted_at`) are skipped from the form body. Per-field overrides declared on
  * `Resource.formFields` win over the inferred defaults.
  *
- * Every dynamic value flows through `escapeHtml()` so a malicious
- * column value rendered into an edit form cannot smuggle markup. The
- * lint sweep at `tests/unit/no-unescaped-interpolation.test.ts`
- * enforces the convention.
+ * The builder precomputes everything inker's `{{ }}` grammar cannot express —
+ * `encodeURIComponent` on the URL components (inker only HTML-escapes), the
+ * per-field variant discriminants, and pre-stringified values — and hands it to
+ * `templates/form.inker`, which iterates + interpolates. inker owns the
+ * HTML-escaping (the retired `escape.ts` no longer runs here). The CSRF hidden
+ * input is emitted by inker's canonical `{{ csrfField() }}` helper, guarded by
+ * the precomputed `csrfEnabled` boolean; enforcement remains story 57.6.
  */
 
 import type { ColumnMetadata } from "@c9up/atlas";
 import type { FormFieldOverride, Resource } from "../types.js";
-import { escapeHtml, safeHtml } from "./escape.js";
-import { renderLayout } from "./layout.js";
 
 const SKIPPED_COLUMN_NAMES: ReadonlySet<string> = new Set([
 	"created_at",
@@ -26,68 +27,126 @@ const SKIPPED_COLUMN_NAMES: ReadonlySet<string> = new Set([
 	"deleted_at",
 ]);
 
+type InputType = NonNullable<FormFieldOverride["inputType"]>;
+
 export interface FormPageInput {
 	resource: Resource;
 	columns: ReadonlyArray<ColumnMetadata>;
 	pkColumn: string;
 	/** Existing row for edit; undefined for create. */
 	row?: Readonly<Record<string, unknown>>;
+	/**
+	 * Submitted values to repopulate the fields with, INDEPENDENT of `row`
+	 * (57.7). On a 422 re-render the form must echo what the user just typed —
+	 * for a *create* that means field values with NO `row` (so `isEdit` stays
+	 * false and the action URL stays `/admin/<slug>`), and for an *edit* it means
+	 * the submitted values while `row` still supplies the id/action. When absent,
+	 * fields fall back to `row` (the normal create/edit GET render).
+	 */
+	values?: Readonly<Record<string, unknown>>;
 	/** Validation errors keyed by column propertyKey. */
 	errors?: Readonly<Record<string, string>>;
-	/** Caller-controlled hidden inputs (e.g. CSRF token). */
-	hiddenInputs?: ReadonlyArray<{ name: string; value: string }>;
+	/**
+	 * Whether the host has a CSRF token in the per-request store. When true the
+	 * template emits `{{ csrfField() }}`; the handler derives it from
+	 * `ctx.store` (57.3). Replaces the old `hiddenInputs?` array.
+	 */
+	csrfEnabled?: boolean;
+}
+
+/** A single form field descriptor consumed by `form.inker`. */
+export interface FormField {
+	name: string;
+	fieldId: string;
+	label: string;
+	inputType: InputType;
+	isCheckbox: boolean;
+	isTextarea: boolean;
+	value: string;
+	required: boolean;
+	placeholder: string;
+	hasPlaceholder: boolean;
+	checked: boolean;
+	error: string;
 }
 
-export function renderFormPage(input: FormPageInput): string {
-	const { resource, columns, pkColumn, row, errors, hiddenInputs } = input;
+// A `type` alias (not `interface`) so the view-model carries an implicit index
+// signature and stays assignable to the renderer's
+// `Readonly<Record<string, unknown>>` data param without a cast.
+export type FormViewModel = {
+	title: string;
+	heading: string;
+	isEdit: boolean;
+	action: string;
+	cancelUrl: string;
+	submitLabel: string;
+	csrfEnabled: boolean;
+	fields: FormField[];
+};
+
+export function buildFormViewModel(input: FormPageInput): FormViewModel {
+	const { resource, columns, pkColumn, row, values, errors, csrfEnabled } =
+		input;
 	const isEdit = row !== undefined;
 	const slug = encodeURIComponent(resource.name);
 	const id = isEdit ? String(row[pkColumn] ?? "") : "";
+	// Contains `encodeURIComponent(` + the structural `slug`, so the
+	// no-unescaped-interpolation grep-ban allows these interpolation slots.
 	const action = isEdit
 		? `/admin/${slug}/${encodeURIComponent(id)}`
 		: `/admin/${slug}`;
-	const methodOverride = isEdit
-		? `<input type="hidden" name="_method" value="PUT">`
-		: "";
+	// Composed via array `join` (no `${}`, no `+`) so neither biome's
+	// useTemplate nor the grep-ban fires on this now-data-only file (show.ts:50).
 	const heading = isEdit
-		? `Edit ${escapeHtml(resource.label)} #${escapeHtml(id)}`
-		: `New ${escapeHtml(resource.label)}`;
-
-	const hiddens = (hiddenInputs ?? [])
-		.map(
-			(h) =>
-				`<input type="hidden" name="${escapeHtml(h.name)}" value="${escapeHtml(h.value)}">`,
-		)
-		.join("");
+		? ["Edit ", resource.label, " #", id].join("")
+		: ["New ", resource.label].join("");
 
-	const fieldHtml = columns
+	const fields = columns
 		.filter(
 			(c) => !shouldSkipColumn(c, pkColumn, resource.formFields[c.propertyKey]),
 		)
-		.map((c) => renderField(c, row, errors, resource.formFields[c.propertyKey]))
-		.join("");
-
-	const submitLabel = isEdit ? "Update" : "Create";
-	const cancelUrl = isEdit
-		? `/admin/${slug}/${encodeURIComponent(id)}`
-		: `/admin/${slug}`;
-
-	const body =
-		`<h1>${heading}</h1>` +
-		`<form class="st-form" method="POST" action="${escapeHtml(action)}">` +
-		methodOverride +
-		hiddens +
-		fieldHtml +
-		`<div class="st-form-actions">` +
-		`<button type="submit">${escapeHtml(submitLabel)}</button>` +
-		`<a class="st-cancel" href="${escapeHtml(cancelUrl)}">Cancel</a>` +
-		`</div>` +
-		`</form>`;
+		.map((c) =>
+			buildField(c, values ?? row, errors, resource.formFields[c.propertyKey]),
+		);
+
+	return {
+		title: heading,
+		heading,
+		isEdit,
+		action,
+		cancelUrl: action,
+		submitLabel: isEdit ? "Update" : "Create",
+		csrfEnabled: csrfEnabled === true,
+		fields,
+	};
+}
 
-	return renderLayout({
-		title: isEdit ? `Edit ${resource.label} #${id}` : `New ${resource.label}`,
-		bodyHtml: safeHtml(body),
-	});
+function buildField(
+	c: ColumnMetadata,
+	source: Readonly<Record<string, unknown>> | undefined,
+	errors: Readonly<Record<string, string>> | undefined,
+	override: FormFieldOverride | undefined,
+): FormField {
+	const inputType = override?.inputType ?? inferInputType(c);
+	const name = c.propertyKey;
+	const rawValue = source?.[name];
+	const isCheckbox = inputType === "checkbox";
+	const value =
+		rawValue === undefined || rawValue === null ? "" : String(rawValue);
+	return {
+		name,
+		fieldId: ["f-", name].join(""),
+		label: override?.label ?? titleise(name),
+		inputType,
+		isCheckbox,
+		isTextarea: inputType === "textarea",
+		value,
+		required: override?.required === true,
+		placeholder: override?.placeholder ?? "",
+		hasPlaceholder: override?.placeholder !== undefined,
+		checked: isCheckbox ? Boolean(rawValue) : false,
+		error: errors?.[name] ?? "",
+	};
 }
 
 function shouldSkipColumn(
@@ -108,68 +167,7 @@ function shouldSkipColumn(
 	return false;
 }
 
-function renderField(
-	c: ColumnMetadata,
-	row: Readonly<Record<string, unknown>> | undefined,
-	errors: Readonly<Record<string, string>> | undefined,
-	override: FormFieldOverride | undefined,
-): string {
-	const inputType = override?.inputType ?? inferInputType(c);
-	const labelText = override?.label ?? titleise(c.propertyKey);
-	const required = override?.required === true ? " required" : "";
-	const placeholder =
-		override?.placeholder !== undefined
-			? ` placeholder="${escapeHtml(override.placeholder)}"`
-			: "";
-	const name = c.propertyKey;
-	const fieldId = `f-${escapeHtml(name)}`;
-	const rawValue = row?.[name];
-	const errorMsg = errors?.[name];
-	const errorHtml =
-		errorMsg !== undefined
-			? `<p class="st-field-error">${escapeHtml(errorMsg)}</p>`
-			: "";
-
-	const input = renderInput(
-		inputType,
-		fieldId,
-		name,
-		rawValue,
-		required,
-		placeholder,
-	);
-
-	return (
-		`<div class="st-field">` +
-		`<label for="${escapeHtml(fieldId)}">${escapeHtml(labelText)}</label>` +
-		input +
-		errorHtml +
-		`</div>`
-	);
-}
-
-/** Render the `<input>` / `<textarea>` element for a field by input type. */
-function renderInput(
-	inputType: FormFieldOverride["inputType"],
-	fieldId: string,
-	name: string,
-	rawValue: unknown,
-	required: string,
-	placeholder: string,
-): string {
-	if (inputType === "checkbox") {
-		const checked = rawValue ? " checked" : "";
-		return `<input id="${escapeHtml(fieldId)}" type="checkbox" name="${escapeHtml(name)}" value="1"${checked}>`;
-	}
-	const value =
-		rawValue === undefined || rawValue === null ? "" : String(rawValue);
-	if (inputType === "textarea") {
-		return `<textarea id="${escapeHtml(fieldId)}" name="${escapeHtml(name)}"${required}${placeholder}>${escapeHtml(value)}</textarea>`;
-	}
-	return `<input id="${escapeHtml(fieldId)}" type="${escapeHtml(inputType)}" name="${escapeHtml(name)}" value="${escapeHtml(value)}"${required}${placeholder}>`;
-}
-
-function inferInputType(c: ColumnMetadata): FormFieldOverride["inputType"] {
+function inferInputType(c: ColumnMetadata): InputType {
 	const type = (c.type ?? "").toString().toLowerCase();
 	if (type === "boolean") return "checkbox";
 	if (type === "integer" || type === "bigint" || type === "number") {

package/src/views/list.ts

@@ -1,16 +1,16 @@
 /**
  * `GET /admin/<slug>` — paginated list view.
  *
- * Pure `(input) => string` renderer. Every dynamic value flows through
- * `escapeHtml()` or `encodeURIComponent()` (URL components). The
- * "interpolation must wrap" rule is grep-enforced by
- * `tests/unit/no-unescaped-interpolation.test.ts`.
+ * Pure `(input) => ListViewModel` builder. It precomputes everything the
+ * inker `{{ }}` grammar cannot express — `encodeURIComponent` on URL
+ * components (inker only HTML-escapes), the pager-collapse shape, the
+ * caption bounds, and each row flattened to pre-stringified `cells` — and
+ * hands it to `templates/list.inker`, which iterates and interpolates.
+ * inker owns the HTML-escaping (the retired `escape.ts` no longer runs here).
  */
 
 import type { ColumnMetadata } from "@c9up/atlas";
 import type { Resource } from "../types.js";
-import { escapeHtml, safeHtml } from "./escape.js";
-import { renderLayout } from "./layout.js";
 
 export interface ListPageInput {
 	resource: Resource;
@@ -23,99 +23,132 @@ export interface ListPageInput {
 	lastPage: number;
 }
 
-export function renderListPage(input: ListPageInput): string {
+/** A pager step (prev / next) — an anchor unless it is the edge (disabled). */
+export interface ListPagerStep {
+	href: string;
+	disabled: boolean;
+}
+
+/** A numbered pager slot, or an ellipsis gap when `isEllipsis`. */
+export interface ListPagerPage {
+	n: number;
+	href: string;
+	isCurrent: boolean;
+	isEllipsis: boolean;
+}
+
+/** A single data row: pre-stringified cells + the precomputed Show href. */
+export interface ListRow {
+	cells: string[];
+	showHref: string;
+}
+
+// A `type` alias (not `interface`) so the view-model carries an implicit
+// index signature and stays assignable to the renderer's
+// `Readonly<Record<string, unknown>>` data param without a cast.
+export type ListViewModel = {
+	title: string;
+	heading: string;
+	labelLower: string;
+	empty: boolean;
+	columns: string[];
+	rows: ListRow[];
+	pager: {
+		prev: ListPagerStep;
+		next: ListPagerStep;
+		pages: ListPagerPage[];
+	};
+	caption: { show: boolean; start: number; end: number; total: number };
+};
+
+export function buildListViewModel(input: ListPageInput): ListViewModel {
 	const { resource, rows, columns, pkColumn, page, perPage, total, lastPage } =
 		input;
 	const slug = encodeURIComponent(resource.name);
-	const body =
-		rows.length === 0
-			? renderEmptyState(resource)
-			: renderTable(rows, columns, pkColumn, slug);
-	const pager = renderPager(slug, page, perPage, lastPage);
-	const caption = renderCaption(page, perPage, total);
-	return renderLayout({
+	const columnKeys = columns.map((c) => c.propertyKey);
+	return {
 		title: resource.label,
-		bodyHtml: safeHtml(
-			`<h1>${escapeHtml(resource.label)}</h1>${body}${pager}${caption}`,
-		),
-	});
-}
-
-function renderEmptyState(resource: Resource): string {
-	return `<p class="st-empty">No ${escapeHtml(resource.label.toLowerCase())} yet.</p>`;
+		heading: resource.label,
+		labelLower: resource.label.toLowerCase(),
+		empty: rows.length === 0,
+		columns: columnKeys,
+		rows: rows.map((row) => ({
+			cells: columns.map((c) => stringifyCell(row[c.propertyKey])),
+			showHref: `/admin/${slug}/${encodeURIComponent(String(row[pkColumn] ?? ""))}`,
+		})),
+		pager: buildPager(slug, page, perPage, lastPage),
+		caption: buildCaption(page, perPage, total),
+	};
 }
 
-function renderTable(
-	rows: ReadonlyArray<Record<string, unknown>>,
-	columns: ReadonlyArray<ColumnMetadata>,
-	pkColumn: string,
-	slug: string,
-): string {
-	const headers = columns
-		.map((c) => `<th>${escapeHtml(c.propertyKey)}</th>`)
-		.join("");
-	const headerRow = `<thead><tr>${headers}<th></th></tr></thead>`;
-	const bodyRows = rows
-		.map((row) => {
-			const cells = columns
-				.map((c) => `<td>${escapeHtml(row[c.propertyKey])}</td>`)
-				.join("");
-			const id = String(row[pkColumn] ?? "");
-			const showLink = `<td><a href="/admin/${slug}/${encodeURIComponent(id)}">Show</a></td>`;
-			return `<tr>${cells}${showLink}</tr>`;
-		})
-		.join("");
-	return `<table>${headerRow}<tbody>${bodyRows}</tbody></table>`;
+/** Match the retired escaper's `null | undefined` → `""` behaviour. */
+function stringifyCell(value: unknown): string {
+	return value === null || value === undefined ? "" : String(value);
 }
 
-function renderPager(
+function buildPager(
 	slug: string,
 	page: number,
 	perPage: number,
 	lastPage: number,
-): string {
+): ListViewModel["pager"] {
 	const pp = encodeURIComponent(String(perPage));
-	const prev =
-		page > 1
-			? `<a href="/admin/${slug}?page=${page - 1}&perPage=${pp}">« Prev</a>`
-			: `<span class="st-disabled">« Prev</span>`;
-	const next =
-		page < lastPage
-			? `<a href="/admin/${slug}?page=${page + 1}&perPage=${pp}">Next »</a>`
-			: `<span class="st-disabled">Next »</span>`;
-	const numbers = renderPageNumbers(slug, page, lastPage, pp);
-	return `<div class="st-pager">${prev}${numbers}${next}</div>`;
+	const href = (n: number): string => `/admin/${slug}?page=${n}&perPage=${pp}`;
+	return {
+		prev: { href: page > 1 ? href(page - 1) : "", disabled: page <= 1 },
+		next: {
+			href: page < lastPage ? href(page + 1) : "",
+			disabled: page >= lastPage,
+		},
+		pages: buildPageNumbers(slug, page, lastPage, pp),
+	};
 }
 
-function renderPageNumbers(
+function buildPageNumbers(
 	slug: string,
 	page: number,
 	lastPage: number,
 	pp: string,
-): string {
-	const link = (n: number): string =>
-		n === page
-			? `<strong>${n}</strong>`
-			: `<a href="/admin/${slug}?page=${n}&perPage=${pp}">${n}</a>`;
+): ListPagerPage[] {
+	const href = (n: number): string => `/admin/${slug}?page=${n}&perPage=${pp}`;
+	const numbered = (n: number): ListPagerPage => ({
+		n,
+		href: href(n),
+		isCurrent: n === page,
+		isEllipsis: false,
+	});
+	const ellipsis: ListPagerPage = {
+		n: 0,
+		href: "",
+		isCurrent: false,
+		isEllipsis: true,
+	};
 	if (lastPage <= 7) {
-		const parts: string[] = [];
-		for (let i = 1; i <= lastPage; i++) parts.push(link(i));
-		return parts.join("");
+		const parts: ListPagerPage[] = [];
+		for (let i = 1; i <= lastPage; i++) parts.push(numbered(i));
+		return parts;
 	}
 	// Collapsed shape: 1 … current-1, current, current+1 … lastPage
-	const parts: string[] = [link(1)];
+	const parts: ListPagerPage[] = [numbered(1)];
 	const start = Math.max(2, page - 1);
 	const end = Math.min(lastPage - 1, page + 1);
-	if (start > 2) parts.push(`<span class="st-ellipsis">…</span>`);
-	for (let i = start; i <= end; i++) parts.push(link(i));
-	if (end < lastPage - 1) parts.push(`<span class="st-ellipsis">…</span>`);
-	parts.push(link(lastPage));
-	return parts.join("");
+	if (start > 2) parts.push(ellipsis);
+	for (let i = start; i <= end; i++) parts.push(numbered(i));
+	if (end < lastPage - 1) parts.push(ellipsis);
+	parts.push(numbered(lastPage));
+	return parts;
 }
 
-function renderCaption(page: number, perPage: number, total: number): string {
-	if (total === 0) return "";
-	const start = (page - 1) * perPage + 1;
-	const end = Math.min(page * perPage, total);
-	return `<p class="st-caption">Showing ${start}–${end} of ${total}</p>`;
+function buildCaption(
+	page: number,
+	perPage: number,
+	total: number,
+): ListViewModel["caption"] {
+	if (total === 0) return { show: false, start: 0, end: 0, total };
+	return {
+		show: true,
+		start: (page - 1) * perPage + 1,
+		end: Math.min(page * perPage, total),
+		total,
+	};
 }

package/src/views/login.ts

@@ -5,13 +5,14 @@
  * `buildLoginHandler` runs them through `auth.authenticate(...)` and
  * sets a session cookie on success.
  *
- * Every dynamic value flows through `escapeHtml()` so a tampered
- * `?error=…` query parameter cannot smuggle markup into the page.
+ * Pure `(input) => LoginViewModel` builder (Story 57.3): every value reaches
+ * HTML through `templates/login.inker`'s `{{ }}` auto-escape (the retired
+ * `escape.ts` no longer runs here), so a tampered `?error=…` query parameter
+ * cannot smuggle markup into the page. The CSRF hidden input is emitted by
+ * inker's canonical `{{ csrfField() }}` helper, guarded by the precomputed
+ * `csrfEnabled` boolean.
  */
 
-import { escapeHtml, safeHtml } from "./escape.js";
-import { renderLayout } from "./layout.js";
-
 export interface LoginPageInput {
 	/** Pre-fill the email field (e.g. after a failed attempt). */
 	email?: string;
@@ -19,47 +20,33 @@ export interface LoginPageInput {
 	error?: string;
 	/** Form action path. Default `/admin/login`. */
 	action?: string;
-	/** Caller-controlled hidden inputs (typically `_csrf`). */
-	hiddenInputs?: ReadonlyArray<{ name: string; value: string }>;
+	/**
+	 * Whether the host has a CSRF token in the per-request store. When true the
+	 * template emits `{{ csrfField() }}`; the handler derives it from
+	 * `ctx.store` (57.3). Replaces the old `hiddenInputs?` array.
+	 */
+	csrfEnabled?: boolean;
 }
 
-export function renderLoginPage(input: LoginPageInput): string {
-	const email = input.email ?? "";
-	const error = input.error;
-	const action = input.action ?? "/admin/login";
-
-	const hiddens = (input.hiddenInputs ?? [])
-		.map(
-			(h) =>
-				`<input type="hidden" name="${escapeHtml(h.name)}" value="${escapeHtml(h.value)}">`,
-		)
-		.join("");
-
-	const errorBlock =
-		error !== undefined
-			? `<p class="st-form-error" role="alert">${escapeHtml(error)}</p>`
-			: "";
-
-	const body =
-		`<h1>Sign in</h1>` +
-		errorBlock +
-		`<form class="st-form" method="POST" action="${escapeHtml(action)}">` +
-		hiddens +
-		`<div class="st-field">` +
-		`<label for="f-email">Email</label>` +
-		`<input id="f-email" type="email" name="email" value="${escapeHtml(email)}" required autocomplete="email" autofocus>` +
-		`</div>` +
-		`<div class="st-field">` +
-		`<label for="f-password">Password</label>` +
-		`<input id="f-password" type="password" name="password" required autocomplete="current-password">` +
-		`</div>` +
-		`<div class="st-form-actions">` +
-		`<button type="submit">Sign in</button>` +
-		`</div>` +
-		`</form>`;
+// A `type` alias (not `interface`) so the view-model carries an implicit index
+// signature and stays assignable to the renderer's
+// `Readonly<Record<string, unknown>>` data param without a cast.
+export type LoginViewModel = {
+	title: string;
+	email: string;
+	action: string;
+	error: string;
+	csrfEnabled: boolean;
+};
 
-	return renderLayout({
+export function buildLoginViewModel(input: LoginPageInput): LoginViewModel {
+	return {
 		title: "Sign in",
-		bodyHtml: safeHtml(body),
-	});
+		email: input.email ?? "",
+		// No URL-encoding: the login action is a fixed host-configured path.
+		action: input.action ?? "/admin/login",
+		// Empty string is falsy in inker, so `{% if error %}` gates the block.
+		error: input.error ?? "",
+		csrfEnabled: input.csrfEnabled === true,
+	};
 }