@velastack/cms 0.6.3 → 0.6.5

package/dist/components/cms/cms-form-fields.svelte

@@ -0,0 +1,68 @@
+<script lang="ts" module>
+	/** `CmsFormFields`: a form's inputs as content editors can change. */
+	export * from '../../core/shapes/form-fields.js';
+</script>
+
+<script lang="ts">
+	/**
+	 * Goes inside a `CmsForm` or `CmsWhatsAppForm`. Renders one input per
+	 * field through the template's `field` snippet, or plain labelled inputs
+	 * without one. Editors add, remove, reorder and retype fields from the
+	 * pencil; each field's submitted `name` stays put (see the shape).
+	 */
+	import type { Snippet } from 'svelte';
+	import Structured from './cms-structured.svelte';
+	import {
+		cmsFormFields,
+		formFieldsView,
+		type CmsFormFieldItem,
+		type CmsFormFieldsValue
+	} from '../../core/shapes/form-fields.js';
+
+	type Props = {
+		name: string;
+		scope?: string;
+		/** The full value, or a bare field list. */
+		fallback?: Partial<CmsFormFieldsValue> | Array<Partial<CmsFormFieldItem>>;
+		value?: unknown;
+		field?: Snippet<[CmsFormFieldItem]>;
+	};
+	let { name, scope, fallback, value, field }: Props = $props();
+</script>
+
+{#snippet plain(f: CmsFormFieldItem)}
+	<label class="cms-form-field" data-type={f.type}>
+		{#if f.type === 'checkbox'}
+			<input type="checkbox" name={f.name} value="yes" required={f.required} />
+			<span>{f.label}</span>
+		{:else}
+			<span>{f.label}</span>
+			{#if f.type === 'textarea'}
+				<textarea name={f.name} required={f.required} placeholder={f.placeholder || undefined}
+				></textarea>
+			{:else if f.type === 'select'}
+				<select name={f.name} required={f.required}>
+					<option value="">{f.placeholder}</option>
+					{#each f.options as option, i (i)}
+						<option>{option}</option>
+					{/each}
+				</select>
+			{:else}
+				<input
+					type={f.type}
+					name={f.name}
+					required={f.required}
+					placeholder={f.placeholder || undefined}
+				/>
+			{/if}
+		{/if}
+	</label>
+{/snippet}
+
+<Structured schema={cmsFormFields} {name} {scope} {fallback} {value} view={formFieldsView}>
+	{#snippet children(fields)}
+		{#each fields as f (f.id)}
+			{@render (field ?? plain)(f)}
+		{/each}
+	{/snippet}
+</Structured>

package/dist/components/cms/cms-form-fields.svelte.d.ts

@@ -0,0 +1,21 @@
+/** `CmsFormFields`: a form's inputs as content editors can change. */
+export * from '../../core/shapes/form-fields.js';
+/**
+     * Goes inside a `CmsForm` or `CmsWhatsAppForm`. Renders one input per
+     * field through the template's `field` snippet, or plain labelled inputs
+     * without one. Editors add, remove, reorder and retype fields from the
+     * pencil; each field's submitted `name` stays put (see the shape).
+     */
+import type { Snippet } from 'svelte';
+import { type CmsFormFieldItem, type CmsFormFieldsValue } from '../../core/shapes/form-fields.js';
+type Props = {
+    name: string;
+    scope?: string;
+    /** The full value, or a bare field list. */
+    fallback?: Partial<CmsFormFieldsValue> | Array<Partial<CmsFormFieldItem>>;
+    value?: unknown;
+    field?: Snippet<[CmsFormFieldItem]>;
+};
+declare const CmsFormFields: import("svelte").Component<Props, {}, "">;
+type CmsFormFields = ReturnType<typeof CmsFormFields>;
+export default CmsFormFields;

package/dist/components/cms/cms-form.svelte

@@ -0,0 +1,99 @@
+<script lang="ts" module>
+	import type { FormStatus } from './use-form-target.svelte.js';
+
+	export type { FormStatus as CmsFormStatus };
+
+	/** What `children` gets: how the last submission went. */
+	export type CmsFormState = {
+		readonly status: FormStatus;
+		/** The endpoint's or action's message on `failure` / `error`. */
+		readonly message: string | null;
+		/** The action's returned data on `success` / `failure`. */
+		readonly data: Record<string, unknown> | null;
+	};
+</script>
+
+<script lang="ts">
+	/**
+	 * `CmsForm`: a form that posts to a hosted form by `key`, or to the
+	 * template's own `action`. The inputs are the template's children.
+	 *
+	 * It is a real `<form method="POST">`, so it works without JavaScript;
+	 * with it, `use:enhance` posts in place and `children` sees the status.
+	 * The hosted endpoint answers enhanced posts the way a SvelteKit action
+	 * does, so both destinations behave the same. Results are handled here
+	 * rather than by the default callback, which would reload the page's data
+	 * on success and send a network failure to the error page.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLFormAttributes } from 'svelte/elements';
+	import { enhance, type SubmitFunction } from '$app/forms';
+	import { cmsStore } from './cms-store.svelte.js';
+	import { followRedirect, useFormTarget } from './use-form-target.svelte.js';
+	import FormControls from './cms-form-controls.svelte';
+
+	type Props = Omit<HTMLFormAttributes, 'action' | 'method' | 'children'> & {
+		/** A hosted form's key, as the template manifest declares it. */
+		key?: string;
+		/** Post here instead: a route, or a SvelteKit action like `?/contact`. */
+		action?: string;
+		/** Where to go after a successful submission. */
+		redirect?: string;
+		children: Snippet<[CmsFormState]>;
+	};
+	let { key, action, redirect, children, ...rest }: Props = $props();
+
+	const target = useFormTarget(() => ({ key, action }));
+
+	let status = $state<FormStatus>('idle');
+	let message = $state<string | null>(null);
+	let data = $state<Record<string, unknown> | null>(null);
+	const formState: CmsFormState = {
+		get status() {
+			return status;
+		},
+		get message() {
+			return message;
+		},
+		get data() {
+			return data;
+		}
+	};
+
+	const messageOf = (value: unknown): string | null =>
+		value && typeof value === 'object' && 'message' in value && typeof value.message === 'string'
+			? value.message
+			: null;
+
+	const submit: SubmitFunction = ({ cancel }) => {
+		// Editors are changing the page, not filling it in.
+		if (cmsStore.isEditing) return cancel();
+		status = 'submitting';
+		message = null;
+		data = null;
+		return async ({ result, formElement, update }) => {
+			if (result.type === 'success') {
+				status = 'success';
+				data = result.data ?? null;
+				formElement.reset();
+				if (redirect) await followRedirect(redirect);
+			} else if (result.type === 'failure') {
+				status = 'failure';
+				data = result.data ?? null;
+				message = messageOf(result.data);
+			} else if (result.type === 'redirect') {
+				// A same-app action redirected; let SvelteKit follow it.
+				status = 'success';
+				await update();
+			} else {
+				status = 'error';
+				message = messageOf(result.error);
+			}
+		};
+	};
+</script>
+
+<form {...rest} method="POST" action={target.url} use:enhance={submit}>
+	<FormControls {redirect} token={target.token} />
+	{@render children(formState)}
+</form>

package/dist/components/cms/cms-form.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { FormStatus } from './use-form-target.svelte.js';
+export type { FormStatus as CmsFormStatus };
+/** What `children` gets: how the last submission went. */
+export type CmsFormState = {
+    readonly status: FormStatus;
+    /** The endpoint's or action's message on `failure` / `error`. */
+    readonly message: string | null;
+    /** The action's returned data on `success` / `failure`. */
+    readonly data: Record<string, unknown> | null;
+};
+/**
+     * `CmsForm`: a form that posts to a hosted form by `key`, or to the
+     * template's own `action`. The inputs are the template's children.
+     *
+     * It is a real `<form method="POST">`, so it works without JavaScript;
+     * with it, `use:enhance` posts in place and `children` sees the status.
+     * The hosted endpoint answers enhanced posts the way a SvelteKit action
+     * does, so both destinations behave the same. Results are handled here
+     * rather than by the default callback, which would reload the page's data
+     * on success and send a network failure to the error page.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
+type Props = Omit<HTMLFormAttributes, 'action' | 'method' | 'children'> & {
+    /** A hosted form's key, as the template manifest declares it. */
+    key?: string;
+    /** Post here instead: a route, or a SvelteKit action like `?/contact`. */
+    action?: string;
+    /** Where to go after a successful submission. */
+    redirect?: string;
+    children: Snippet<[CmsFormState]>;
+};
+declare const CmsForm: import("svelte").Component<Props, {}, "">;
+type CmsForm = ReturnType<typeof CmsForm>;
+export default CmsForm;

package/dist/components/cms/cms-whatsapp-form-editable.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	/**
+	 * The editor for `CmsWhatsAppForm`: the shape's fields, plus the
+	 * `{placeholders}` the form's inputs provide, read from the form when the
+	 * popover opens so fields added through `CmsFormFields` show up too.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { Tree } from '../../core/path.js';
+	import type { FormShape } from '../../core/shapes/form.js';
+	import type { CmsWhatsAppValue } from '../../core/shapes/whatsapp.js';
+	import type { CmsField } from './use-cms-field.svelte.js';
+	import { getWhatsAppFieldNames } from './cms-whatsapp-form.svelte';
+	import StructuredEditorPopover from '../admin-bar/structured-editor-popover.svelte';
+	import FieldsForm from '../admin-bar/fields-form.svelte';
+
+	type Props = {
+		field: CmsField<CmsWhatsAppValue>;
+		schema: FormShape<CmsWhatsAppValue>;
+		preview: Snippet;
+	};
+	let { field, schema, preview }: Props = $props();
+
+	const fieldNames = getWhatsAppFieldNames();
+</script>
+
+<StructuredEditorPopover {field} {schema} label={schema.label} {preview}>
+	{#snippet editor(draft: CmsWhatsAppValue, update: (next: CmsWhatsAppValue) => void)}
+		{@const names = fieldNames()}
+		<FieldsForm
+			fields={schema.fields}
+			value={draft as Tree}
+			onChange={(next) => update(next as CmsWhatsAppValue)}
+		/>
+		{#if names.length > 0}
+			<p class="vela:text-[11px] vela:text-bar-text-tertiary vela:m-0">
+				Placeholders:
+				{#each names as name (name)}
+					<code class="vela:font-mono vela:mr-1">{`{${name}}`}</code>
+				{/each}
+			</p>
+		{/if}
+	{/snippet}
+</StructuredEditorPopover>

package/dist/components/cms/cms-whatsapp-form-editable.svelte.d.ts

@@ -0,0 +1,17 @@
+/**
+     * The editor for `CmsWhatsAppForm`: the shape's fields, plus the
+     * `{placeholders}` the form's inputs provide, read from the form when the
+     * popover opens so fields added through `CmsFormFields` show up too.
+     */
+import type { Snippet } from 'svelte';
+import type { FormShape } from '../../core/shapes/form.js';
+import type { CmsWhatsAppValue } from '../../core/shapes/whatsapp.js';
+import type { CmsField } from './use-cms-field.svelte.js';
+type Props = {
+    field: CmsField<CmsWhatsAppValue>;
+    schema: FormShape<CmsWhatsAppValue>;
+    preview: Snippet;
+};
+declare const CmsWhatsappFormEditable: import("svelte").Component<Props, {}, "">;
+type CmsWhatsappFormEditable = ReturnType<typeof CmsWhatsappFormEditable>;
+export default CmsWhatsappFormEditable;

package/dist/components/cms/cms-whatsapp-form.svelte

@@ -0,0 +1,167 @@
+<script lang="ts" module>
+	/** `CmsWhatsAppForm`: a form whose answers open a prefilled WhatsApp chat. */
+	import { getContext } from 'svelte';
+	import { isControlField } from '../../core/forms/target.js';
+	import type { CmsFormState } from './cms-form.svelte';
+
+	export * from '../../core/shapes/whatsapp.js';
+
+	export type CmsWhatsAppFormState = CmsFormState & {
+		/** A chat link with no message, for a `<noscript>` fallback; `null` without a number. */
+		readonly whatsappHref: string | null;
+	};
+
+	const FIELD_NAMES = Symbol('vela-cms:whatsapp-field-names');
+
+	/** For the settings editor: the `{placeholders}` this form's inputs provide. */
+	export const getWhatsAppFieldNames = (): (() => string[]) =>
+		getContext<() => string[]>(FIELD_NAMES) ?? (() => []);
+
+	const fieldNames = (form: HTMLFormElement): string[] => {
+		const names = new Set<string>();
+		for (const el of form.elements) {
+			const name = (el as HTMLInputElement).name;
+			const type = (el as HTMLInputElement).type;
+			if (name && !isControlField(name) && type !== 'submit' && type !== 'button') names.add(name);
+		}
+		return [...names];
+	};
+</script>
+
+<script lang="ts">
+	/**
+	 * Like `CmsForm`, but a submission opens `wa.me` with the editor's
+	 * message (answers substituted for `{field}` placeholders) addressed to
+	 * the editor's number. The answers are also posted in the background, so
+	 * the lead is kept even if the visitor never sends the chat.
+	 *
+	 * The chat opens inside the submit handler, before the post settles: a
+	 * popup opened after an `await` loses the click's user activation and is
+	 * blocked. `keepalive` lets the post finish if the page goes away. If the
+	 * popup is blocked anyway, this tab goes to WhatsApp instead.
+	 *
+	 * Without JavaScript the form posts normally, so the answers are still
+	 * stored and `redirect` applies; `whatsappHref` is there for a
+	 * `<noscript>` link.
+	 */
+	import { setContext, type Snippet } from 'svelte';
+	import type { HTMLFormAttributes } from 'svelte/elements';
+	import Structured from './cms-structured.svelte';
+	import FormControls from './cms-form-controls.svelte';
+	import { cmsStore } from './cms-store.svelte.js';
+	import { followRedirect, useFormTarget, type FormStatus } from './use-form-target.svelte.js';
+	import { cmsWhatsApp, type CmsWhatsAppValue } from '../../core/shapes/whatsapp.js';
+	import { fillMessage, whatsappHref } from '../../core/forms/whatsapp.js';
+
+	type Props = Omit<HTMLFormAttributes, 'action' | 'method' | 'children'> & {
+		/** The CMS field holding the number and message. */
+		name: string;
+		scope?: string;
+		fallback?: Partial<CmsWhatsAppValue>;
+		value?: unknown;
+		/** A hosted form's key, to record each submission to. */
+		key?: string;
+		/** Record to this route or SvelteKit action instead. */
+		action?: string;
+		/** Where this tab goes once the chat has opened in a new one. */
+		redirect?: string;
+		children: Snippet<[CmsWhatsAppFormState]>;
+	};
+	let {
+		name,
+		scope,
+		fallback,
+		value,
+		key,
+		action,
+		redirect,
+		children: content,
+		...rest
+	}: Props = $props();
+
+	const target = useFormTarget(() => ({ key, action }));
+
+	let formEl = $state<HTMLFormElement>();
+	setContext(FIELD_NAMES, () => (formEl ? fieldNames(formEl) : []));
+
+	let status = $state<FormStatus>('idle');
+	let message = $state<string | null>(null);
+
+	const stateFor = (settings: CmsWhatsAppValue): CmsWhatsAppFormState => ({
+		get status() {
+			return status;
+		},
+		get message() {
+			return message;
+		},
+		data: null,
+		whatsappHref: whatsappHref(settings.number)
+	});
+
+	const record = (body: FormData) => {
+		if (!target.url) {
+			status = 'success';
+			return;
+		}
+		body.delete('_redirect');
+		status = 'submitting';
+		fetch(target.url, {
+			method: 'POST',
+			body,
+			keepalive: true,
+			headers: { accept: 'application/json' }
+		})
+			.then(async (res) => {
+				status = res.ok ? 'success' : 'failure';
+				if (!res.ok) message = ((await res.json().catch(() => null))?.message as string) ?? null;
+			})
+			.catch(() => {
+				status = 'error';
+			});
+	};
+
+	const submit = (event: SubmitEvent, settings: CmsWhatsAppValue) => {
+		event.preventDefault();
+		if (cmsStore.isEditing) return;
+		const form = event.currentTarget as HTMLFormElement;
+		const body = new FormData(form, event.submitter);
+		const href = whatsappHref(settings.number, fillMessage(settings.message, body));
+		message = null;
+		record(body);
+		if (!href) {
+			status = 'error';
+			message = 'No WhatsApp number is set.';
+			return;
+		}
+		const chat = window.open(href, '_blank');
+		if (!chat) {
+			location.assign(href);
+			return;
+		}
+		chat.opener = null;
+		if (redirect) void followRedirect(redirect);
+	};
+</script>
+
+<Structured
+	schema={cmsWhatsApp}
+	{name}
+	{scope}
+	{fallback}
+	{value}
+	view={(settings) => settings}
+	editable={() => import('./cms-whatsapp-form-editable.svelte')}
+>
+	{#snippet children(settings)}
+		<form
+			{...rest}
+			method="POST"
+			action={target.url}
+			bind:this={formEl}
+			onsubmit={(event) => submit(event, settings)}
+		>
+			<FormControls {redirect} token={target.token} />
+			{@render content(stateFor(settings))}
+		</form>
+	{/snippet}
+</Structured>

package/dist/components/cms/cms-whatsapp-form.svelte.d.ts

@@ -0,0 +1,43 @@
+import type { CmsFormState } from './cms-form.svelte';
+export * from '../../core/shapes/whatsapp.js';
+export type CmsWhatsAppFormState = CmsFormState & {
+    /** A chat link with no message, for a `<noscript>` fallback; `null` without a number. */
+    readonly whatsappHref: string | null;
+};
+/** For the settings editor: the `{placeholders}` this form's inputs provide. */
+export declare const getWhatsAppFieldNames: () => (() => string[]);
+/**
+     * Like `CmsForm`, but a submission opens `wa.me` with the editor's
+     * message (answers substituted for `{field}` placeholders) addressed to
+     * the editor's number. The answers are also posted in the background, so
+     * the lead is kept even if the visitor never sends the chat.
+     *
+     * The chat opens inside the submit handler, before the post settles: a
+     * popup opened after an `await` loses the click's user activation and is
+     * blocked. `keepalive` lets the post finish if the page goes away. If the
+     * popup is blocked anyway, this tab goes to WhatsApp instead.
+     *
+     * Without JavaScript the form posts normally, so the answers are still
+     * stored and `redirect` applies; `whatsappHref` is there for a
+     * `<noscript>` link.
+     */
+import { type Snippet } from 'svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
+import { type CmsWhatsAppValue } from '../../core/shapes/whatsapp.js';
+type Props = Omit<HTMLFormAttributes, 'action' | 'method' | 'children'> & {
+    /** The CMS field holding the number and message. */
+    name: string;
+    scope?: string;
+    fallback?: Partial<CmsWhatsAppValue>;
+    value?: unknown;
+    /** A hosted form's key, to record each submission to. */
+    key?: string;
+    /** Record to this route or SvelteKit action instead. */
+    action?: string;
+    /** Where this tab goes once the chat has opened in a new one. */
+    redirect?: string;
+    children: Snippet<[CmsWhatsAppFormState]>;
+};
+declare const CmsWhatsappForm: import("svelte").Component<Props, {}, "">;
+type CmsWhatsappForm = ReturnType<typeof CmsWhatsappForm>;
+export default CmsWhatsappForm;

package/dist/components/cms/index.d.ts

@@ -23,5 +23,10 @@ export { default as CmsGallery } from './cms-gallery.svelte';
 export { default as CmsLogos } from './cms-logos.svelte';
 export { default as CmsSchedule } from './cms-schedule.svelte';
 export { default as CmsEntries } from './cms-entries.svelte';
+export { default as CmsForm } from './cms-form.svelte';
+export type { CmsFormState, CmsFormStatus } from './cms-form.svelte';
+export { default as CmsFormFields } from './cms-form-fields.svelte';
+export { default as CmsWhatsAppForm } from './cms-whatsapp-form.svelte';
+export type { CmsWhatsAppFormState } from './cms-whatsapp-form.svelte';
 export { CMS_SCOPE, getCmsScope, getCmsValue } from './scope.js';
 export type { CmsScope, CmsPayload, CmsEntry } from './scope.js';

package/dist/components/cms/index.js

@@ -22,4 +22,7 @@ export { default as CmsGallery } from './cms-gallery.svelte';
 export { default as CmsLogos } from './cms-logos.svelte';
 export { default as CmsSchedule } from './cms-schedule.svelte';
 export { default as CmsEntries } from './cms-entries.svelte';
+export { default as CmsForm } from './cms-form.svelte';
+export { default as CmsFormFields } from './cms-form-fields.svelte';
+export { default as CmsWhatsAppForm } from './cms-whatsapp-form.svelte';
 export { CMS_SCOPE, getCmsScope, getCmsValue } from './scope.js';

package/dist/components/cms/use-form-target.svelte.d.ts

@@ -0,0 +1,18 @@
+export type FormStatus = 'idle' | 'submitting' | 'success' | 'failure' | 'error';
+export type FormTargetInput = {
+    key?: string;
+    action?: string;
+};
+/**
+ * After an enhanced post, go where `_redirect` would have sent a post
+ * without JavaScript. The hosted endpoint never answers an enhanced post
+ * with a redirect (the client would hand an external URL to `goto`), so the
+ * form follows it itself.
+ */
+export declare const followRedirect: (redirect: string) => Promise<void>;
+export type FormTarget = {
+    /** The form's `action`; `undefined` posts back to the page. */
+    readonly url: string | undefined;
+    readonly token: string | null;
+};
+export declare const useFormTarget: (input: () => FormTargetInput) => FormTarget;

package/dist/components/cms/use-form-target.svelte.js

@@ -0,0 +1,68 @@
+/**
+ * Where a `CmsForm` or `CmsWhatsAppForm` posts, and the load-time token a
+ * hosted form wants with it.
+ *
+ * `action` wins when given: the template's own route or SvelteKit action.
+ * Otherwise `key` names a hosted form beside the CMS endpoint (see
+ * `core/forms/target.ts`). The token only exists for hosted forms. It is
+ * fetched on mount because the endpoint refuses one younger than two
+ * seconds; a post without it is still stored, just as unverified.
+ */
+import { dev } from '$app/env';
+import { goto } from '$app/navigation';
+import { cms } from './cms-store.svelte.js';
+import { hostedFormUrl } from '../../core/forms/target.js';
+/**
+ * After an enhanced post, go where `_redirect` would have sent a post
+ * without JavaScript. The hosted endpoint never answers an enhanced post
+ * with a redirect (the client would hand an external URL to `goto`), so the
+ * form follows it itself.
+ */
+export const followRedirect = async (redirect) => {
+    const url = new URL(redirect, location.href);
+    if (url.origin === location.origin)
+        await goto(url.href);
+    else
+        location.assign(url.href);
+};
+export const useFormTarget = (input) => {
+    const hosted = $derived.by(() => {
+        const { key, action } = input();
+        return action === undefined && key ? hostedFormUrl(cms.endpoint, key) : null;
+    });
+    const url = $derived(input().action ?? hosted ?? undefined);
+    let token = $state(null);
+    $effect(() => {
+        const target = hosted;
+        token = null;
+        if (!target)
+            return;
+        let live = true;
+        fetch(target, { headers: { accept: 'application/json' } })
+            .then((res) => (res.ok ? res.json() : null))
+            .then((body) => {
+            if (live && typeof body?.token === 'string')
+                token = body.token;
+        })
+            .catch(() => { });
+        return () => {
+            live = false;
+        };
+    });
+    $effect(() => {
+        if (dev && url === undefined) {
+            const { key } = input();
+            console.warn(key
+                ? `[cms] Form "${key}" has no hosted endpoint (CMS endpoint "${cms.endpoint}"); pass \`action\`.`
+                : '[cms] Form has neither `key` nor `action`; it will post back to the page.');
+        }
+    });
+    return {
+        get url() {
+            return url;
+        },
+        get token() {
+            return token;
+        }
+    };
+};

package/dist/core/forms/target.d.ts

@@ -0,0 +1,3 @@
+export declare const hostedFormUrl: (endpoint: string, key: string) => string | null;
+/** Fields a form carries for the endpoint rather than the submission. */
+export declare const isControlField: (name: string) => boolean;

package/dist/core/forms/target.js

@@ -0,0 +1,16 @@
+/**
+ * Where a form posts when the template names a hosted form by `key`.
+ *
+ * velastack.dev serves a project's CMS at `/v1/projects/<id>/cms` and its
+ * hosted forms beside it at `/v1/projects/<id>/forms/<key>`, the forms a
+ * template's manifest declares. Any other endpoint shape (a same-app
+ * `/api/cms`, this package's own `/cms` backend) has no hosted forms, so
+ * there is nothing to derive and the template passes `action` instead.
+ */
+const HOSTED_CMS = /^(.*\/v1\/projects\/[^/?#]+)\/cms\/?$/;
+export const hostedFormUrl = (endpoint, key) => {
+    const match = HOSTED_CMS.exec(endpoint);
+    return match ? `${match[1]}/forms/${encodeURIComponent(key)}` : null;
+};
+/** Fields a form carries for the endpoint rather than the submission. */
+export const isControlField = (name) => name.startsWith('_');

package/dist/core/forms/whatsapp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Building the `wa.me` link a `CmsWhatsAppForm` opens: the editor's format
+ * string with the visitor's answers substituted, sent to the editor's number.
+ */
+/**
+ * Substitute `{field}` placeholders with the submitted values. A field sent
+ * more than once (checkboxes, multi-selects) joins with commas; a placeholder
+ * with no matching field, and file uploads, become empty.
+ */
+export declare const fillMessage: (template: string, data: FormData) => string;
+/**
+ * The digits `wa.me` wants: country code and number, no `+`, spaces or
+ * dashes. A leading `00` international prefix is dropped, since no country
+ * code starts with 0.
+ */
+export declare const whatsappNumber: (raw: string) => string;
+/** `https://wa.me/<number>?text=<message>`, or `null` when no number is set. */
+export declare const whatsappHref: (number: string, message?: string) => string | null;