@marianmeres/stuic 3.126.0 → 3.127.0

package/dist/components/ContactUsForm/README.md

@@ -0,0 +1,211 @@
+# ContactUsForm
+
+Drop-in "contact us" form built from the STUIC `Field*` primitives. Same conventions as [`RegisterForm`](../RegisterForm/README.md): bindable `formData`, an `onSubmit` callback, inline + server validation, i18n via `t`, optional `notifications`, declarative `extraFields`, and an `extraFieldsSlot` escape hatch.
+
+By default it renders the **absolute minimum** — an **Email** and a **Message** field — and everything else is opt-in via `show*` toggles, `extraFields`, or the slot. There are **no server wirings**: you get the data (and the bot signals) in `onSubmit` and decide what to do with them.
+
+## Bot protection
+
+Two **client-side, server-less** anti-bot primitives are rendered by default and reused from the Input package — [`Honeypot`](../Input/README.md#honeypot--time-trap-anti-bot-primitives) and [`TimeTrap`](../Input/README.md#honeypot--time-trap-anti-bot-primitives):
+
+- **Honeypot** — a hidden field real users never see; a non-empty value means a bot filled it.
+- **TimeTrap** — flags submits that arrive faster than a human plausibly could (`timeTrapMinMs`, default 2000).
+
+These are **report-only**: the form **never blocks** a submit because of them. Instead it hands you a `botCheck` object as the **second argument** to `onSubmit` — you enforce server-side (drop / rate-limit / queue for review). This is the right division of labor for a server-less component: the library provides the signals, your backend decides. For hard protection against targeted bots in 2026 you still want a real challenge (Cloudflare Turnstile / hCaptcha) verified on your server — render its widget through the `extraFieldsSlot`.
+
+## Exports
+
+| Export                       | Kind      | Description                                                |
+| ---------------------------- | --------- | ---------------------------------------------------------- |
+| `ContactUsForm`              | component | The form component                                         |
+| `ContactUsFormProps`         | type      | Props for `ContactUsForm`                                  |
+| `ContactFormData`            | type      | `{ name, email, phone, subject, company, message, extra }` |
+| `ContactBotCheck`            | type      | Anti-bot signals passed as the 2nd `onSubmit` arg          |
+| `ContactFormValidationError` | type      | `{ field, message }`                                       |
+| `ContactFieldConfig`         | type      | Declarative extra-field descriptor                         |
+| `createEmptyContactFormData` | function  | Factory for an empty `ContactFormData`                     |
+| `ValidateContactFormOptions` | type      | Options accepted by the internal validator                 |
+
+## `ContactBotCheck`
+
+```ts
+interface ContactBotCheck {
+	honeypot: string; // raw honeypot value ("" = clean)
+	honeypotFilled: boolean; // true when the trap was filled
+	elapsedMs: number; // ms between form mount and submit
+	isTooFast: boolean; // elapsedMs < minMs
+	minMs: number; // the configured timeTrapMinMs
+	isLikelyBot: boolean; // honeypotFilled || isTooFast
+}
+```
+
+## `ContactFieldConfig`
+
+```ts
+interface ContactFieldConfig {
+	name: string; // unique key under formData.extra
+	label: string; // already-translated
+	type?: "text" | "email" | "tel" | "url" | "number";
+	placeholder?: string;
+	required?: boolean;
+	autocomplete?: HTMLInputAttributes["autocomplete"];
+	initialValue?: unknown;
+	validate?: (value: unknown, data: ContactFormData) => string | undefined;
+	position?: "top" | "bottom"; // default "bottom"
+	props?: Record<string, unknown>; // passthrough to FieldInput
+}
+```
+
+## Props
+
+| Prop                 | Type                                                         | Default  | Description                                                                                                         |
+| -------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `formData`           | `ContactFormData`                                            | empty    | Bindable form data.                                                                                                 |
+| `onSubmit`           | `(data: ContactFormData, botCheck: ContactBotCheck) => void` | required | Called after client-side validation passes. `botCheck` is report-only.                                              |
+| `isSubmitting`       | `boolean`                                                    | `false`  | Disables the CTA during submission.                                                                                 |
+| `errors`             | `ContactFormValidationError[]`                               | `[]`     | Field-specific server errors (merged with internal validation).                                                     |
+| `error`              | `string`                                                     | -        | General error rendered as a `DismissibleMessage` above the form.                                                    |
+| `showName`           | `boolean`                                                    | `false`  | Render the Name field.                                                                                              |
+| `requireName`        | `boolean`                                                    | `true`   | Require Name (only applies when shown).                                                                             |
+| `showPhone`          | `boolean`                                                    | `false`  | Render the Phone field.                                                                                             |
+| `requirePhone`       | `boolean`                                                    | `false`  | Require Phone (only applies when shown).                                                                            |
+| `showSubject`        | `boolean`                                                    | `false`  | Render the Subject field (free text).                                                                               |
+| `requireSubject`     | `boolean`                                                    | `false`  | Require Subject (only applies when shown).                                                                          |
+| `subjectValues`      | `string[]`                                                   | -        | If set, Subject renders as a `<select>` of these values (and is auto-shown). A blank "Select…" prompt is prepended. |
+| `showCompany`        | `boolean`                                                    | `false`  | Render the Company field.                                                                                           |
+| `requireCompany`     | `boolean`                                                    | `false`  | Require Company (only applies when shown).                                                                          |
+| `messageMinLength`   | `number`                                                     | `0`      | Minimum message length. `0` disables the check.                                                                     |
+| `extraFields`        | `ContactFieldConfig[]`                                       | `[]`     | Declarative extra fields, positioned top or bottom.                                                                 |
+| `extraFieldsSlot`    | `Snippet<[{ formData, fieldError }]>`                        | -        | Escape hatch for non-FieldInput extras (consent checkbox, captcha widget).                                          |
+| `useHoneypot`        | `boolean`                                                    | `true`   | Render the hidden honeypot trap.                                                                                    |
+| `honeypotName`       | `string`                                                     | `"link"` | Honeypot field name. Avoid browser-autofill tokens (`url`/`name`/`email`/…).                                        |
+| `useTimeTrap`        | `boolean`                                                    | `true`   | Render the time-trap.                                                                                               |
+| `timeTrapMinMs`      | `number`                                                     | `2000`   | Minimum plausible human fill time (ms).                                                                             |
+| `submitLabel`        | `string`                                                     | i18n     | Override the CTA label.                                                                                             |
+| `submittingLabel`    | `string`                                                     | i18n     | Override the CTA label while submitting.                                                                            |
+| `submitButton`       | `Snippet<[{ isSubmitting, disabled }]>`                      | -        | Override the entire CTA section.                                                                                    |
+| `footer`             | `Snippet`                                                    | -        | Content below the form.                                                                                             |
+| `notifications`      | `NotificationsStack`                                         | -        | When set, general errors are also pushed via `notifications.error()`.                                               |
+| `t`                  | `TranslateFn`                                                | English  | i18n function.                                                                                                      |
+| `unstyled` / `class` | -                                                            | -        | Standard styling escape hatches.                                                                                    |
+| `el`                 | `HTMLFormElement`                                            | -        | Bindable form element.                                                                                              |
+
+### Imperative methods (via `bind:this`)
+
+| Method                      | Returns   | Purpose                                                             |
+| --------------------------- | --------- | ------------------------------------------------------------------- |
+| `validate()`                | `boolean` | Forces every visible field's validator to run. `true` if all valid. |
+| `scrollToFirstError(opts?)` | `boolean` | Scrolls + focuses the first invalid field. Call after `validate()`. |
+
+## Usage
+
+### Basic (Email + Message only)
+
+```svelte
+<script lang="ts">
+	import { ContactUsForm } from "@marianmeres/stuic";
+
+	async function send(data, botCheck) {
+		// Enforce the bot signals on YOUR server — the form never blocks.
+		await fetch("/api/contact", {
+			method: "POST",
+			body: JSON.stringify({ ...data, botCheck }),
+		});
+	}
+</script>
+
+<ContactUsForm onSubmit={send} />
+```
+
+### Standard layout (Name + Subject)
+
+```svelte
+<ContactUsForm onSubmit={send} showName showSubject requireSubject />
+```
+
+### Subject as a dropdown
+
+Pass `subjectValues` to render the Subject as a `<select>` (the field is shown
+automatically; the bound value is still the chosen string in `formData.subject`).
+
+```svelte
+<ContactUsForm
+	onSubmit={send}
+	requireSubject
+	subjectValues={["General enquiry", "Sales", "Support", "Feedback"]}
+/>
+```
+
+### Reacting to the bot signals
+
+```svelte
+<script lang="ts">
+	import { ContactUsForm } from "@marianmeres/stuic";
+
+	function onSubmit(data, botCheck) {
+		if (botCheck.isLikelyBot) {
+			// Silently accept on the client so bots don't learn; drop on the server.
+			console.warn("likely bot", botCheck);
+		}
+		send(data, botCheck);
+	}
+</script>
+
+<ContactUsForm {onSubmit} timeTrapMinMs={3000} />
+```
+
+### With a consent checkbox (extraFieldsSlot)
+
+```svelte
+<script lang="ts">
+	import { ContactUsForm, FieldCheckbox } from "@marianmeres/stuic";
+
+	let formData = $state({
+		name: "",
+		email: "",
+		phone: "",
+		subject: "",
+		company: "",
+		message: "",
+		extra: { consent: false },
+	});
+</script>
+
+<ContactUsForm bind:formData onSubmit={send}>
+	{#snippet extraFieldsSlot({ formData, fieldError })}
+		<FieldCheckbox
+			bind:checked={formData.extra.consent}
+			label="I agree to be contacted"
+			error={fieldError("consent")}
+		/>
+	{/snippet}
+</ContactUsForm>
+```
+
+### Declarative extra field
+
+```svelte
+<ContactUsForm
+	onSubmit={send}
+	extraFields={[
+		{ name: "orderId", label: "Order number", position: "top", autocomplete: "off" },
+	]}
+/>
+```
+
+## CSS Variables
+
+Prefix: `--stuic-contact-us-form-*`
+
+| Variable                      | Purpose                       |
+| ----------------------------- | ----------------------------- |
+| `--stuic-contact-us-form-gap` | Vertical gap between sections |
+
+## i18n keys
+
+Under the `contact_form.*` namespace. See `_internal/contact-form-i18n-defaults.ts` for the full list and English defaults.
+
+## See also
+
+- [Input](../Input/README.md) — the `Field*` primitives this form is built from, including the `Honeypot` and `TimeTrap` anti-bot primitives.
+- [RegisterForm](../RegisterForm/README.md) — same form conventions (declarative extras, `extraFieldsSlot`, imperative API).

package/dist/components/ContactUsForm/_internal/contact-form-i18n-defaults.d.ts

@@ -0,0 +1 @@
+export declare function t_default(k: string, values?: false | null | undefined | Record<string, string | number>, fallback?: string | boolean): string;

package/dist/components/ContactUsForm/_internal/contact-form-i18n-defaults.js

@@ -0,0 +1,36 @@
+import { isPlainObject } from "../../../utils/is-plain-object.js";
+import { replaceMap } from "../../../utils/replace-map.js";
+const DEFAULTS = {
+    "contact_form.name_label": "Name",
+    "contact_form.name_placeholder": "",
+    "contact_form.email_label": "Email",
+    "contact_form.email_placeholder": "you@example.com",
+    "contact_form.phone_label": "Phone",
+    "contact_form.phone_placeholder": "",
+    "contact_form.company_label": "Company",
+    "contact_form.company_placeholder": "",
+    "contact_form.subject_label": "Subject",
+    "contact_form.subject_placeholder": "",
+    "contact_form.subject_select_prompt": "Select…",
+    "contact_form.message_label": "Message",
+    "contact_form.message_placeholder": "How can we help?",
+    "contact_form.submit": "Send message",
+    "contact_form.submitting": "Sending...",
+    "contact_form.name_required": "Name is required",
+    "contact_form.email_required": "Email is required",
+    "contact_form.email_invalid": "Please enter a valid email address",
+    "contact_form.phone_required": "Phone is required",
+    "contact_form.subject_required": "Subject is required",
+    "contact_form.company_required": "Company is required",
+    "contact_form.message_required": "Message is required",
+    "contact_form.message_too_short": "Message must be at least {min} characters",
+    "contact_form.field_required": "{label} is required",
+};
+export function t_default(k, values = null, fallback = "") {
+    const out = DEFAULTS[k] ?? (typeof fallback === "string" ? fallback : "") ?? k;
+    return isPlainObject(values)
+        ? replaceMap(out, values, {
+            preSearchKeyTransform: (k) => `{${k}}`,
+        })
+        : out;
+}

package/dist/components/ContactUsForm/_internal/contact-form-types.d.ts

@@ -0,0 +1,59 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+export interface ContactFormData {
+    name: string;
+    email: string;
+    phone: string;
+    subject: string;
+    company: string;
+    message: string;
+    /** Values for consumer-defined extraFields, keyed by field name. */
+    extra: Record<string, unknown>;
+}
+export interface ContactFormValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * Anti-bot signals surfaced as the 2nd argument to `onSubmit`.
+ *
+ * Report-only: ContactUsForm never blocks a submit on these — enforce them
+ * server-side (drop / rate-limit / queue-for-review). `isLikelyBot` is a
+ * convenience OR of the individual signals.
+ */
+export interface ContactBotCheck {
+    /** Raw honeypot value. A non-empty value means a bot filled the hidden trap. */
+    honeypot: string;
+    /** `true` when the honeypot was filled. */
+    honeypotFilled: boolean;
+    /** Milliseconds between form mount and submit. */
+    elapsedMs: number;
+    /** `true` when `elapsedMs < minMs` (submitted suspiciously fast). */
+    isTooFast: boolean;
+    /** The configured minimum fill time (ms). */
+    minMs: number;
+    /** `honeypotFilled || isTooFast`. */
+    isLikelyBot: boolean;
+}
+/** Declarative descriptor for a consumer-defined FieldInput-style extra field. */
+export interface ContactFieldConfig {
+    /** Key under `formData.extra` where the value lives. Must be unique. */
+    name: string;
+    /** Visible label (already translated; ContactUsForm does not apply `t()` here). */
+    label: string;
+    /** FieldInput `type`. Default "text". */
+    type?: "text" | "email" | "tel" | "url" | "number";
+    placeholder?: string;
+    required?: boolean;
+    autocomplete?: HTMLInputAttributes["autocomplete"];
+    /** Initial value to seed into `formData.extra[name]` if undefined. */
+    initialValue?: unknown;
+    /**
+     * Synchronous validator. Return empty string / undefined for "valid".
+     * Return a message string for "invalid" (wired into the same error pipeline).
+     */
+    validate?: (value: unknown, data: ContactFormData) => string | undefined;
+    /** Render before the message field ("top") or after it ("bottom"). Default "bottom". */
+    position?: "top" | "bottom";
+    /** Extra passthrough props merged onto FieldInput. */
+    props?: Record<string, unknown>;
+}

package/dist/components/ContactUsForm/_internal/contact-form-types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/ContactUsForm/_internal/contact-form-utils.d.ts

@@ -0,0 +1,17 @@
+import type { ContactFieldConfig, ContactFormData, ContactFormValidationError } from "./contact-form-types.js";
+import type { TranslateFn } from "../../../types.js";
+export interface ValidateContactFormOptions {
+    showName?: boolean;
+    requireName?: boolean;
+    showPhone?: boolean;
+    requirePhone?: boolean;
+    showSubject?: boolean;
+    requireSubject?: boolean;
+    showCompany?: boolean;
+    requireCompany?: boolean;
+    /** Minimum message length. 0 (default) disables the check. */
+    messageMinLength?: number;
+    extraFields?: ContactFieldConfig[];
+}
+export declare function validateContactForm(data: ContactFormData, t: TranslateFn, options?: ValidateContactFormOptions): ContactFormValidationError[];
+export declare function createEmptyContactFormData(): ContactFormData;

package/dist/components/ContactUsForm/_internal/contact-form-utils.js

@@ -0,0 +1,66 @@
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+export function validateContactForm(data, t, options = {}) {
+    const { showName = false, requireName = true, showPhone = false, requirePhone = false, showSubject = false, requireSubject = false, showCompany = false, requireCompany = false, messageMinLength = 0, extraFields = [], } = options;
+    const errors = [];
+    // Email — always present, always validated.
+    const trimmedEmail = data.email.trim();
+    if (!trimmedEmail) {
+        errors.push({ field: "email", message: t("contact_form.email_required") });
+    }
+    else if (!EMAIL_RE.test(trimmedEmail)) {
+        errors.push({ field: "email", message: t("contact_form.email_invalid") });
+    }
+    // Message — always present, always required.
+    const trimmedMessage = data.message.trim();
+    if (!trimmedMessage) {
+        errors.push({ field: "message", message: t("contact_form.message_required") });
+    }
+    else if (messageMinLength > 0 && trimmedMessage.length < messageMinLength) {
+        errors.push({
+            field: "message",
+            message: t("contact_form.message_too_short", { min: messageMinLength }),
+        });
+    }
+    // Optional toggled fields — only validated when shown AND required.
+    if (showName && requireName && !data.name.trim()) {
+        errors.push({ field: "name", message: t("contact_form.name_required") });
+    }
+    if (showPhone && requirePhone && !data.phone.trim()) {
+        errors.push({ field: "phone", message: t("contact_form.phone_required") });
+    }
+    if (showSubject && requireSubject && !data.subject.trim()) {
+        errors.push({ field: "subject", message: t("contact_form.subject_required") });
+    }
+    if (showCompany && requireCompany && !data.company.trim()) {
+        errors.push({ field: "company", message: t("contact_form.company_required") });
+    }
+    // Consumer-defined extra fields.
+    for (const cfg of extraFields) {
+        const value = data.extra?.[cfg.name];
+        const asString = typeof value === "string" ? value : value == null ? "" : String(value);
+        if (cfg.required && !asString.trim()) {
+            errors.push({
+                field: cfg.name,
+                message: t("contact_form.field_required", { label: cfg.label }),
+            });
+            continue;
+        }
+        if (cfg.validate) {
+            const msg = cfg.validate(value, data);
+            if (msg)
+                errors.push({ field: cfg.name, message: msg });
+        }
+    }
+    return errors;
+}
+export function createEmptyContactFormData() {
+    return {
+        name: "",
+        email: "",
+        phone: "",
+        subject: "",
+        company: "",
+        message: "",
+        extra: {},
+    };
+}

package/dist/components/ContactUsForm/index.css

@@ -0,0 +1,22 @@
+:root {
+	/* ContactUsForm */
+	--stuic-contact-us-form-gap: 0rem;
+}
+
+@layer components {
+	.stuic-contact-us-form {
+		display: flex;
+		flex-direction: column;
+		gap: var(--stuic-contact-us-form-gap);
+	}
+
+	.stuic-contact-us-form-submit {
+		margin-top: 1.5rem;
+		margin-bottom: 1.5rem;
+	}
+}
+
+/* Tighten default FieldInput bottom margin (mb-8 → 1rem) inside the form */
+.stuic-contact-us-form .stuic-input {
+	margin-bottom: 1rem;
+}

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

@@ -0,0 +1,4 @@
+export { default as ContactUsForm, type Props as ContactUsFormProps, } from "./ContactUsForm.svelte";
+export { createEmptyContactFormData } from "./_internal/contact-form-utils.js";
+export type { ValidateContactFormOptions } from "./_internal/contact-form-utils.js";
+export type { ContactFormData, ContactFormValidationError, ContactBotCheck, ContactFieldConfig, } from "./_internal/contact-form-types.js";

package/dist/components/ContactUsForm/index.js

@@ -0,0 +1,2 @@
+export { default as ContactUsForm, } from "./ContactUsForm.svelte";
+export { createEmptyContactFormData } from "./_internal/contact-form-utils.js";

package/dist/components/Input/Honeypot.svelte

@@ -0,0 +1,94 @@
+<script lang="ts" module>
+	import type { HTMLInputAttributes } from "svelte/elements";
+
+	export interface Props extends Omit<HTMLInputAttributes, "value" | "name"> {
+		/**
+		 * Current trap value. Real users never see the field, so a non-empty value
+		 * is a strong "this was filled by a bot" signal. Bindable.
+		 */
+		value?: string;
+		/**
+		 * Name (and id) of the trap field. Pick something a naive bot finds
+		 * tempting to fill, that your real form does NOT use, and — importantly —
+		 * that browser/profile autofill does NOT recognize as a known field.
+		 * Avoid `url`/`website`/`email`/`name`/`phone`/`address`/`company`: those
+		 * are exactly what Chrome/Safari autofill writes into, which would fill the
+		 * off-screen trap for a real user and create a false positive. Default:
+		 * "link" (tempting to link-spam bots, ignored by autofill).
+		 */
+		name?: string;
+		id?: string;
+		/**
+		 * Screen-reader-only instruction. The wrapper is `aria-hidden`, so this is
+		 * a belt-and-suspenders fallback for the rare AT that ignores aria-hidden.
+		 * Default: "Leave this field empty".
+		 */
+		label?: string;
+		/** Wrapper element ref. Bindable. */
+		el?: HTMLDivElement;
+		/** Underlying `<input>` ref. Bindable. */
+		input?: HTMLInputElement;
+		/**
+		 * Drop the `stuic-honeypot` class. The hiding styles are applied inline and
+		 * are NOT affected by this — a honeypot must stay hidden to function.
+		 */
+		unstyled?: boolean;
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import { getId } from "../../utils/get-id.js";
+	import { twMerge } from "../../utils/tw-merge.js";
+
+	let {
+		value = $bindable(""),
+		name = "link",
+		id = getId(),
+		label = "Leave this field empty",
+		el = $bindable(),
+		input = $bindable(),
+		unstyled = false,
+		class: classProp,
+		...rest
+	}: Props = $props();
+
+	/** `true` when the trap was filled (i.e. the submitter is likely a bot). */
+	export function isFilled(): boolean {
+		return (value ?? "").trim() !== "";
+	}
+
+	// Hiding here is FUNCTIONAL, not cosmetic: a visible honeypot would be filled
+	// by real users and produce false positives. We inline the hide styles (rather
+	// than rely on a CSS class) so the trap stays hidden even if the consumer has
+	// not imported the library stylesheet — the primitive is self-contained. This
+	// is the standard visually-hidden recipe, kept off-screen rather than
+	// `display:none`/`type=hidden` (which many bots skip).
+	const HIDE_STYLE =
+		"position:absolute !important;width:1px;height:1px;padding:0;margin:-1px;" +
+		"overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;";
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-honeypot", classProp));
+</script>
+
+<!--
+	aria-hidden + tabindex=-1 keep the trap out of the accessibility tree and tab
+	order, so assistive tech and keyboard users never reach it. autocomplete is set
+	to "new-password" — NOT "off", which Chrome/Safari ignore on non-credential text
+	fields — because "new-password" is the value browsers and password managers
+	actually honor as do-not-autofill, so autofill won't write into the trap and
+	falsely flag a real user.
+-->
+<div bind:this={el} class={_class} style={HIDE_STYLE} aria-hidden="true">
+	<label for={id}>{label}</label>
+	<input
+		bind:this={input}
+		bind:value
+		{id}
+		{name}
+		type="text"
+		tabindex={-1}
+		autocomplete="new-password"
+		{...rest}
+	/>
+</div>

package/dist/components/Input/Honeypot.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+export interface Props extends Omit<HTMLInputAttributes, "value" | "name"> {
+    /**
+     * Current trap value. Real users never see the field, so a non-empty value
+     * is a strong "this was filled by a bot" signal. Bindable.
+     */
+    value?: string;
+    /**
+     * Name (and id) of the trap field. Pick something a naive bot finds
+     * tempting to fill, that your real form does NOT use, and — importantly —
+     * that browser/profile autofill does NOT recognize as a known field.
+     * Avoid `url`/`website`/`email`/`name`/`phone`/`address`/`company`: those
+     * are exactly what Chrome/Safari autofill writes into, which would fill the
+     * off-screen trap for a real user and create a false positive. Default:
+     * "link" (tempting to link-spam bots, ignored by autofill).
+     */
+    name?: string;
+    id?: string;
+    /**
+     * Screen-reader-only instruction. The wrapper is `aria-hidden`, so this is
+     * a belt-and-suspenders fallback for the rare AT that ignores aria-hidden.
+     * Default: "Leave this field empty".
+     */
+    label?: string;
+    /** Wrapper element ref. Bindable. */
+    el?: HTMLDivElement;
+    /** Underlying `<input>` ref. Bindable. */
+    input?: HTMLInputElement;
+    /**
+     * Drop the `stuic-honeypot` class. The hiding styles are applied inline and
+     * are NOT affected by this — a honeypot must stay hidden to function.
+     */
+    unstyled?: boolean;
+    class?: string;
+}
+declare const Honeypot: import("svelte").Component<Props, {
+    isFilled: () => boolean;
+}, "el" | "value" | "input">;
+type Honeypot = ReturnType<typeof Honeypot>;
+export default Honeypot;

package/dist/components/Input/README.md

@@ -18,6 +18,8 @@ A comprehensive form input system with multiple field components, validation sup
 | `FieldKeyValues`  | Key-value pairs editor with JSON serialization       |
 | `FieldLikeButton` | Like/favorite toggle button                          |
 | `Fieldset`        | Fieldset with legend                                 |
+| `Honeypot`        | Hidden anti-bot trap field (server-less)             |
+| `TimeTrap`        | Anti-bot submit-timing primitive (server-less)       |
 
 ## Common Props (FieldInput, FieldTextarea, FieldSelect)
 
@@ -439,3 +441,70 @@ A modal-based multi-select/single-select component with search functionality, ty
 <!-- Local customization -->
 <FieldOptions style="--stuic-field-options-divider: var(--color-red-500);" ... />
 ```
+
+---
+
+## Honeypot & TimeTrap (anti-bot primitives)
+
+Two small, **client-side, server-less** primitives for cheap spam mitigation. They produce **signals** — they do not block anything. Read the signal, then enforce on your server (the only place enforcement is trustworthy). Both are reusable on any form; [`ContactUsForm`](../ContactUsForm/README.md) composes them by default.
+
+> These stop a large share of commodity drive-by spam (no UX friction, no external dependency, no privacy/GDPR concern). They do **not** stop a targeted or headless-browser bot — for that you still want a real challenge (Cloudflare Turnstile / hCaptcha) verified server-side.
+
+### `Honeypot`
+
+A visually-hidden, `aria-hidden`, off-screen text input that real users and assistive tech never reach, but naive bots fill. A non-empty value is a strong bot signal. The hiding styles are applied **inline** so the trap stays hidden even without the library stylesheet. The input uses `autocomplete="new-password"` (the value browsers actually honor as do-not-autofill — `autocomplete="off"` is ignored on text fields) so browser/profile autofill won't write into the trap and flag a real user.
+
+```svelte
+<script lang="ts">
+	import { Honeypot } from "@marianmeres/stuic";
+
+	let trap = $state("");
+	// On submit: if trap.trim() !== "" treat as a bot (server-side).
+</script>
+
+<form onsubmit={...}>
+	<!-- ...your real fields... -->
+	<Honeypot bind:value={trap} />
+</form>
+```
+
+| Prop                 | Type          | Default                    | Description                                                                                               |
+| -------------------- | ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `value`              | `string`      | `""`                       | Trap value (bindable). Non-empty ⇒ likely a bot.                                                          |
+| `name`               | `string`      | `"link"`                   | Field name. Default avoids autofill tokens (`url`/`name`/`email`/…). Pick one your real form doesn't use. |
+| `label`              | `string`      | `"Leave this field empty"` | Screen-reader fallback (wrapper is `aria-hidden`).                                                        |
+| `el` / `input`       | `HTMLElement` | -                          | Bindable wrapper / input refs.                                                                            |
+| `unstyled` / `class` | -             | -                          | Drop / extend the `stuic-honeypot` class (hiding is always applied).                                      |
+
+**Method:** `isFilled(): boolean` (via `bind:this`).
+
+> **Naming caveat:** keep the field name tempting to bots but **not** a token browser autofill recognizes. Names like `url`/`website`/`email`/`name`/`phone`/`address` get autofilled into the off-screen trap from the user's saved profile, producing false positives. The default `"link"` and `autocomplete="new-password"` avoid this.
+
+### `TimeTrap`
+
+Records form mount time and flags submits that arrive faster than `minMs`. Renders a single hidden timestamp input (handy for native form POSTs) and exposes reactive `isTooFast` / `elapsedMs` bindings plus a `check()` snapshot for exact submit-time reads.
+
+```svelte
+<script lang="ts">
+	import { TimeTrap } from "@marianmeres/stuic";
+
+	let tooFast = $state(true);
+	let trap = $state<TimeTrap>();
+	// On submit: const { elapsedMs, isTooFast } = trap.check();
+</script>
+
+<TimeTrap bind:this={trap} bind:isTooFast={tooFast} minMs={2000} />
+```
+
+| Prop        | Type      | Default | Description                                                     |
+| ----------- | --------- | ------- | --------------------------------------------------------------- |
+| `minMs`     | `number`  | `2000`  | Minimum plausible human fill time (ms).                         |
+| `enabled`   | `boolean` | `true`  | When false, `isTooFast` stays `false` and no timer runs.        |
+| `isTooFast` | `boolean` | `true`  | Bindable, reactive; `true` until `minMs` elapses.               |
+| `elapsedMs` | `number`  | `0`     | Bindable; updated on the flip and on `check()`.                 |
+| `startedAt` | `number`  | -       | Bindable; epoch ms captured at mount; also in the hidden input. |
+| `name`      | `string`  | `"_ts"` | Name of the rendered hidden timestamp input.                    |
+
+**Methods:** `check(): { elapsedMs, isTooFast, startedAt }`, `reset()` (via `bind:this`).
+
+> The timestamp is a client clock and is **not** tamper-proof. Treat `isTooFast` as a heuristic and pair it with real server-side rate limiting.