@marianmeres/stuic 3.170.0 → 3.172.0

package/dist/components/Input/FieldDateRange.svelte

@@ -0,0 +1,373 @@
+<!--
+	FieldDateRange — pick an inclusive date range (`start` … `end`).
+
+	Both bound ends are ISO `YYYY-MM-DD` strings (or null). The user picks them in
+	a range-mode `Calendar` — first pick anchors, second completes, order-agnostic —
+	in a dialog opened from a trigger showing the formatted range (default), or
+	inline inside the field (`embedded`). Two hidden inputs (`nameStart`, `nameEnd`)
+	carry the ISO values into FormData.
+
+	A half range (start without end) is displayed ("Sep 1, 2026 – …") but fails
+	validation, whether or not the field is `required`.
+-->
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { ValidateOptions } from "../../actions/validate.svelte.js";
+	import type { TranslateFn } from "../../types.js";
+	import type { THC } from "../Thc/Thc.svelte";
+	import type { Props as CalendarProps } from "../Calendar/Calendar.svelte";
+	import type { IsoDate } from "../Calendar/iso-date.js";
+	import type { FieldDateCalendarProps } from "./FieldDate.svelte";
+	import type { InputWrapClassProps } from "./types.js";
+
+	type SnippetWithId = Snippet<[{ id: string }]>;
+
+	/** Payload of `onChange`. */
+	export interface FieldDateRangeValue {
+		start: IsoDate | null;
+		end: IsoDate | null;
+	}
+
+	export interface Props extends InputWrapClassProps, FieldDateCalendarProps {
+		/** Range start as `YYYY-MM-DD` (bindable). */
+		start?: IsoDate | null;
+		/** Range end as `YYYY-MM-DD` (bindable). */
+		end?: IsoDate | null;
+		/** Form field name of the hidden input carrying `start`. */
+		nameStart?: string;
+		/** Form field name of the hidden input carrying `end`. */
+		nameEnd?: string;
+		/** Render the calendar inline inside the field instead of a trigger + dialog. */
+		embedded?: boolean;
+		/** Close the dialog once the range is complete. Default `true`. */
+		closeOnSelect?: boolean;
+		/** Trigger text while empty. Defaults to `t("placeholder_range")`. */
+		placeholder?: string;
+		/** Offer clearing (trailing × on the trigger / "Clear" in the embedded footer). Default `true`. */
+		clearable?: boolean;
+		/** BCP 47 locale of the display text and the calendar names. Browser default when omitted. */
+		locale?: string;
+		/** `Intl.DateTimeFormat` options of the display text. Default `{ dateStyle: "medium" }`. */
+		formatOptions?: Intl.DateTimeFormatOptions;
+		/** Custom display formatter for a complete range (wins over `formatOptions`). */
+		format?: (start: IsoDate, end: IsoDate) => string;
+		/**
+		 * Months the calendar shows side by side at the `md` breakpoint and up (below
+		 * it always a single month). Default `2`.
+		 */
+		months?: number;
+		/** Anything else for the inner `Calendar` (class hooks, `view`, …). Applied last. */
+		calendarProps?: Partial<CalendarProps>;
+		/** The first (start) hidden input (bindable). */
+		input?: HTMLInputElement;
+		label?: SnippetWithId | THC;
+		description?: SnippetWithId | THC;
+		labelAfter?: SnippetWithId | THC;
+		below?: SnippetWithId | THC;
+		class?: string;
+		id?: string;
+		tabindex?: number;
+		renderSize?: "sm" | "md" | "lg" | string;
+		required?: boolean;
+		disabled?: boolean;
+		/**
+		 * Validation. `false` disables the built-in guard (required / complete range /
+		 * valid ISO / min / max / disabled dates); an options object is merged with it
+		 * (your `customValidator` runs after the built-in checks pass). Default: the guard.
+		 */
+		validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+		labelLeft?: boolean;
+		labelLeftWidth?: "normal" | "wide";
+		labelLeftBreakpoint?: number;
+		/** Classes for the trigger button */
+		classInput?: string;
+		/** Classes for the dialog box */
+		classDialog?: string;
+		style?: string;
+		noScrollLock?: boolean;
+		/** i18n — see `createCalendarT`. */
+		t?: TranslateFn;
+		/** Called after either end changed through the picker or the × (not on external writes). */
+		onChange?: (range: FieldDateRangeValue) => void;
+	}
+</script>
+
+<script lang="ts">
+	import { tick } from "svelte";
+	import type { ValidationResult } from "../../actions/validate.svelte.js";
+	import { Breakpoint } from "../../utils/breakpoint.svelte.js";
+	import { getId } from "../../utils/get-id.js";
+	import Button from "../Button/Button.svelte";
+	import Calendar, { type CalendarRangeChange } from "../Calendar/Calendar.svelte";
+	import { t_default } from "../Calendar/calendar-i18n.js";
+	import {
+		compareIso,
+		dayCellOf,
+		DEFAULT_DATE_FORMAT,
+		formatIsoDate,
+		formatIsoDateRange,
+		normalizeIsoDate,
+	} from "../Calendar/iso-date.js";
+	import FieldDateShell from "./_internal/FieldDateShell.svelte";
+
+	let {
+		start = $bindable(null),
+		end = $bindable(null),
+		nameStart,
+		nameEnd,
+		embedded = false,
+		closeOnSelect = true,
+		placeholder,
+		clearable = true,
+		locale,
+		formatOptions,
+		format,
+		months = 2,
+		calendarProps,
+		input = $bindable(),
+		label = "",
+		description,
+		labelAfter,
+		below,
+		class: classProp,
+		id = getId(),
+		tabindex = 0,
+		renderSize = "md",
+		required = false,
+		disabled = false,
+		// Renamed local binding to avoid collision with `export function validate()` below.
+		validate: validateProp,
+		labelLeft = false,
+		labelLeftWidth = "normal",
+		labelLeftBreakpoint = 480,
+		classInput,
+		classDialog,
+		style,
+		noScrollLock = false,
+		t = t_default,
+		onChange,
+		// calendar
+		min,
+		max,
+		isDateDisabled,
+		weekStartsOn,
+		weekendDays,
+		zone,
+		captionLayout,
+		yearRange,
+		showWeekNumbers,
+		showOutsideDays,
+		fixedWeeks,
+		showToday,
+		renderDay,
+		// wrapper class props
+		classLabel,
+		classLabelBox,
+		classInputBox,
+		classInputBoxWrap,
+		classInputBoxWrapInvalid,
+		classDescBox,
+		classDescBoxToggle,
+		classBelowBox,
+		classValidationBox,
+	}: Props = $props();
+
+	let shell: FieldDateShell | undefined = $state();
+
+	const bp = Breakpoint.instance;
+	// two months only fit from the md breakpoint up; phones always get one
+	let effectiveMonths = $derived(bp.md ? months : 1);
+
+	let _start = $derived(normalizeIsoDate(start));
+	let _end = $derived(normalizeIsoDate(end));
+	let _min = $derived(normalizeIsoDate(min));
+	let _max = $derived(normalizeIsoDate(max));
+
+	// Submitted values: the normalized dates, or the raw (unparseable) input so the
+	// validator can flag it instead of silently submitting "".
+	const raw = (v: IsoDate | null | undefined) => (v == null ? "" : `${v}`);
+	let submitStart = $derived(_start ?? raw(start));
+	let submitEnd = $derived(_end ?? raw(end));
+
+	const opts = $derived(formatOptions ?? DEFAULT_DATE_FORMAT);
+	const fmt = (iso: IsoDate): string => formatIsoDate(iso, locale, opts);
+
+	let display = $derived.by(() => {
+		if (_start && _end) {
+			return format
+				? format(_start, _end)
+				: formatIsoDateRange(_start, _end, locale, opts);
+		}
+		if (_start) return `${fmt(_start)} – …`;
+		if (_end) return `… – ${fmt(_end)}`;
+		return "";
+	});
+
+	function commit(s: IsoDate | null, e: IsoDate | null) {
+		start = s;
+		end = e;
+		onChange?.({ start: s, end: e });
+		// let the hidden inputs flush before the validate action reads them
+		tick().then(() => shell?.dispatchChange());
+	}
+
+	function onRangeChange(r: CalendarRangeChange) {
+		commit(r.start, r.end);
+		if (!embedded && closeOnSelect && r.complete) shell?.close();
+	}
+
+	// Built-in guard (hidden inputs never validate natively): required, a complete
+	// range, valid ISO dates, min / max, disabled dates. Consumer opts are honored:
+	// `false` disables; an object is merged (its customValidator runs after the guard).
+	const validateOpts = $derived.by<
+		boolean | Omit<ValidateOptions, "setValidationResult">
+	>(() => {
+		if (validateProp === false) return false;
+		const custom = validateProp && typeof validateProp === "object" ? validateProp : {};
+		return {
+			...custom,
+			// `val` is the start hidden input's value; the end is read from state.
+			customValidator: (val, ctx, el) => {
+				const s = `${val ?? ""}`.trim();
+				const e = submitEnd.trim();
+				if (!s && !e) {
+					if (required) return t("field_req_att");
+					return custom.customValidator?.(val, ctx, el) || "";
+				}
+				if (!s || !e) return t("range_incomplete");
+				const sIso = normalizeIsoDate(s);
+				const eIso = normalizeIsoDate(e);
+				if (!sIso || !eIso) return t("date_invalid");
+				if (compareIso(sIso, eIso) > 0) return t("range_incomplete");
+				for (const iso of [sIso, eIso]) {
+					if (_min && compareIso(iso, _min) < 0) {
+						return t("date_before_min", { value: fmt(_min) });
+					}
+					if (_max && compareIso(iso, _max) > 0) {
+						return t("date_after_max", { value: fmt(_max) });
+					}
+					if (isDateDisabled?.(iso, dayCellOf(iso, { zone, weekendDays }))) {
+						return t("date_disabled");
+					}
+				}
+				return custom.customValidator?.(val, ctx, el) || "";
+			},
+		};
+	});
+
+	// ---- Imperative API (satisfies ValidatableField), forwarded to the shell ----
+
+	/** Trigger validation now. Renders the inline message if invalid. */
+	export function validate(): ValidationResult | undefined {
+		return shell?.validate();
+	}
+
+	/** Clear the inline validation message and reset `setCustomValidity`. */
+	export function clearValidation(): void {
+		shell?.clearValidation();
+	}
+
+	/** Current validation state, or undefined if the validator has never run. */
+	export function getValidation(): ValidationResult | undefined {
+		return shell?.getValidation();
+	}
+
+	/** Focus the trigger (or the embedded calendar's tabbable day). */
+	export function focus(): void {
+		shell?.focus();
+	}
+
+	/** Scroll the field into view. Defaults to smooth + center. */
+	export function scrollIntoView(opts?: ScrollIntoViewOptions): void {
+		shell?.scrollIntoView(opts);
+	}
+
+	/** Open the picker dialog (no-op when `embedded`). */
+	export function open(): void {
+		shell?.open();
+	}
+
+	/** Close the picker dialog. */
+	export function close(): void {
+		shell?.close();
+	}
+</script>
+
+{#snippet doneFooter()}
+	<Button type="button" size="sm" intent="primary" onclick={() => shell?.close()}>
+		{t("done")}
+	</Button>
+{/snippet}
+
+<FieldDateShell
+	bind:this={shell}
+	bind:input
+	{id}
+	{label}
+	{description}
+	{labelAfter}
+	{below}
+	class={classProp}
+	{style}
+	{renderSize}
+	{required}
+	{disabled}
+	{tabindex}
+	{labelLeft}
+	{labelLeftWidth}
+	{labelLeftBreakpoint}
+	{classLabel}
+	{classLabelBox}
+	{classInputBox}
+	{classInputBoxWrap}
+	{classInputBoxWrapInvalid}
+	{classDescBox}
+	{classDescBoxToggle}
+	{classBelowBox}
+	{classValidationBox}
+	{display}
+	placeholder={placeholder ?? t("placeholder_range")}
+	{clearable}
+	clearLabel={t("clear_value")}
+	{embedded}
+	inputs={[
+		{ name: nameStart, value: submitStart },
+		{ name: nameEnd, value: submitEnd },
+	]}
+	validate={validateOpts}
+	dialogTitle={t("dialog_title_range")}
+	closeLabel={t("close")}
+	{noScrollLock}
+	{classInput}
+	{classDialog}
+	onClear={() => commit(null, null)}
+>
+	<Calendar
+		mode="range"
+		start={_start}
+		end={_end}
+		months={effectiveMonths}
+		{min}
+		{max}
+		{isDateDisabled}
+		{weekStartsOn}
+		{weekendDays}
+		{zone}
+		{locale}
+		{captionLayout}
+		{yearRange}
+		{showWeekNumbers}
+		{showOutsideDays}
+		{fixedWeeks}
+		{showToday}
+		showClear={embedded && clearable}
+		{renderDay}
+		{disabled}
+		{t}
+		focusOnMount={!embedded}
+		aria-labelledby={embedded && label ? `${id}-label` : undefined}
+		footer={!embedded && !closeOnSelect ? doneFooter : undefined}
+		{onRangeChange}
+		{...calendarProps}
+	/>
+</FieldDateShell>

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

@@ -0,0 +1,90 @@
+import type { Snippet } from "svelte";
+import type { ValidateOptions } from "../../actions/validate.svelte.js";
+import type { TranslateFn } from "../../types.js";
+import type { THC } from "../Thc/Thc.svelte";
+import type { Props as CalendarProps } from "../Calendar/Calendar.svelte";
+import type { IsoDate } from "../Calendar/iso-date.js";
+import type { FieldDateCalendarProps } from "./FieldDate.svelte";
+import type { InputWrapClassProps } from "./types.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** Payload of `onChange`. */
+export interface FieldDateRangeValue {
+    start: IsoDate | null;
+    end: IsoDate | null;
+}
+export interface Props extends InputWrapClassProps, FieldDateCalendarProps {
+    /** Range start as `YYYY-MM-DD` (bindable). */
+    start?: IsoDate | null;
+    /** Range end as `YYYY-MM-DD` (bindable). */
+    end?: IsoDate | null;
+    /** Form field name of the hidden input carrying `start`. */
+    nameStart?: string;
+    /** Form field name of the hidden input carrying `end`. */
+    nameEnd?: string;
+    /** Render the calendar inline inside the field instead of a trigger + dialog. */
+    embedded?: boolean;
+    /** Close the dialog once the range is complete. Default `true`. */
+    closeOnSelect?: boolean;
+    /** Trigger text while empty. Defaults to `t("placeholder_range")`. */
+    placeholder?: string;
+    /** Offer clearing (trailing × on the trigger / "Clear" in the embedded footer). Default `true`. */
+    clearable?: boolean;
+    /** BCP 47 locale of the display text and the calendar names. Browser default when omitted. */
+    locale?: string;
+    /** `Intl.DateTimeFormat` options of the display text. Default `{ dateStyle: "medium" }`. */
+    formatOptions?: Intl.DateTimeFormatOptions;
+    /** Custom display formatter for a complete range (wins over `formatOptions`). */
+    format?: (start: IsoDate, end: IsoDate) => string;
+    /**
+     * Months the calendar shows side by side at the `md` breakpoint and up (below
+     * it always a single month). Default `2`.
+     */
+    months?: number;
+    /** Anything else for the inner `Calendar` (class hooks, `view`, …). Applied last. */
+    calendarProps?: Partial<CalendarProps>;
+    /** The first (start) hidden input (bindable). */
+    input?: HTMLInputElement;
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    class?: string;
+    id?: string;
+    tabindex?: number;
+    renderSize?: "sm" | "md" | "lg" | string;
+    required?: boolean;
+    disabled?: boolean;
+    /**
+     * Validation. `false` disables the built-in guard (required / complete range /
+     * valid ISO / min / max / disabled dates); an options object is merged with it
+     * (your `customValidator` runs after the built-in checks pass). Default: the guard.
+     */
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    /** Classes for the trigger button */
+    classInput?: string;
+    /** Classes for the dialog box */
+    classDialog?: string;
+    style?: string;
+    noScrollLock?: boolean;
+    /** i18n — see `createCalendarT`. */
+    t?: TranslateFn;
+    /** Called after either end changed through the picker or the × (not on external writes). */
+    onChange?: (range: FieldDateRangeValue) => void;
+}
+import type { ValidationResult } from "../../actions/validate.svelte.js";
+declare const FieldDateRange: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+    open: () => void;
+    close: () => void;
+}, "input" | "end" | "start">;
+type FieldDateRange = ReturnType<typeof FieldDateRange>;
+export default FieldDateRange;

package/dist/components/Input/README.md

@@ -4,22 +4,24 @@ A comprehensive form input system with multiple field components, validation sup
 
 ## Components
 
-| Component         | Description                                          |
-| ----------------- | ---------------------------------------------------- |
-| `FieldInput`      | Text, email, password, number, and other input types |
-| `FieldMoney`      | Money amount stored as integer minor units (cents)   |
-| `FieldTextarea`   | Multi-line text input with auto-grow                 |
-| `FieldSelect`     | Dropdown select with option groups                   |
-| `FieldCheckbox`   | Single checkbox with label                           |
-| `FieldRadios`     | Radio button group                                   |
-| `FieldSwitch`     | Toggle switch field                                  |
-| `FieldFile`       | File upload input                                    |
-| `FieldAssets`     | Asset/image upload with preview                      |
-| `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)       |
+| Component         | Description                                                    |
+| ----------------- | -------------------------------------------------------------- |
+| `FieldInput`      | Text, email, password, number, and other input types           |
+| `FieldMoney`      | Money amount stored as integer minor units (cents)             |
+| `FieldDate`       | Single calendar date — trigger + dialog, or embedded calendar  |
+| `FieldDateRange`  | Inclusive date range (`start` … `end`), same two presentations |
+| `FieldTextarea`   | Multi-line text input with auto-grow                           |
+| `FieldSelect`     | Dropdown select with option groups                             |
+| `FieldCheckbox`   | Single checkbox with label                                     |
+| `FieldRadios`     | Radio button group                                             |
+| `FieldSwitch`     | Toggle switch field                                            |
+| `FieldFile`       | File upload input                                              |
+| `FieldAssets`     | Asset/image upload with preview                                |
+| `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)
 
@@ -734,6 +736,137 @@ until it settles, and a rejection is caught so a failed download never breaks th
 
 ---
 
+## Date and date range fields
+
+`FieldDate` picks one calendar date, `FieldDateRange` an inclusive `start` … `end` pair.
+Both wrap the [`Calendar`](../Calendar/README.md) component in the standard field
+scaffolding (label, description, validation, sizes, the shared class props, the
+imperative API) and come in two presentations:
+
+- **dialog** (default) — a trigger button shows the formatted value (or a placeholder)
+  and opens the calendar in a native `<dialog>`; a pick closes it (`closeOnSelect`), a
+  trailing × clears. Focus moves into the grid on open and back to the trigger on close.
+  On phones the dialog is a centered card with 44px day targets.
+- **embedded** — the calendar sits inline inside the field card, no trigger, no dialog;
+  "Clear" moves into the calendar's footer.
+
+Values are ISO `YYYY-MM-DD` strings (`null` = empty). The `name` (`nameStart` /
+`nameEnd` for the range) goes on **hidden inputs** carrying those ISO values, so a
+`<form>` always submits `2026-09-02` no matter how the date is displayed — `locale`,
+`formatOptions` and `format` only shape the trigger text.
+
+```svelte
+<script lang="ts">
+	import { FieldDate, FieldDateRange, todayIso } from "@marianmeres/stuic";
+
+	let delivery = $state<string | null>(null);
+	let from = $state<string | null>(null);
+	let to = $state<string | null>(null);
+	let dob = $state<string | null>(null);
+</script>
+
+<FieldDate
+	bind:value={delivery}
+	label="Delivery date"
+	name="delivery"
+	min={todayIso()}
+	required
+/>
+
+<FieldDateRange
+	bind:start={from}
+	bind:end={to}
+	label="Stay"
+	nameStart="from"
+	nameEnd="to"
+/>
+
+<!-- inline, with a dropdown caption to reach far-away years -->
+<FieldDate
+	bind:value={dob}
+	label="Date of birth"
+	name="dob"
+	embedded
+	captionLayout="dropdown"
+	yearRange={[1920, 2026]}
+	max={todayIso()}
+/>
+```
+
+### Props
+
+Field-specific:
+
+| Prop            | `FieldDate`        | `FieldDateRange`                        | Description                                                  |
+| --------------- | ------------------ | --------------------------------------- | ------------------------------------------------------------ |
+| value           | `value` (bindable) | `start`, `end` (bindable)               | ISO `YYYY-MM-DD` or `null`                                   |
+| form name       | `name`             | `nameStart`, `nameEnd`                  | Names of the hidden input(s)                                 |
+| `onChange`      | `(value) => void`  | `({ start, end }) => void`              | After a pick / clear through the UI (not on external writes) |
+| `format`        | `(iso) => string`  | `(start, end) => string`                | Custom trigger text (wins over `formatOptions`)              |
+| `months`        | default `1`        | default `2` (collapses to 1 below `md`) | Months side by side in the calendar                          |
+| `closeOnSelect` | close after a pick | close once the range is complete        | Default `true`; `false` keeps the dialog open + adds "Done"  |
+
+Shared:
+
+| Prop            | Type                         | Default                   | Description                                                                                           |
+| --------------- | ---------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `embedded`      | `boolean`                    | `false`                   | Inline calendar instead of trigger + dialog                                                           |
+| `placeholder`   | `string`                     | `t("placeholder_…")`      | Trigger text while empty                                                                              |
+| `clearable`     | `boolean`                    | `true`                    | The trailing × (dialog) / the footer "Clear" (embedded)                                               |
+| `locale`        | `string`                     | browser                   | BCP 47 locale of the trigger text and the calendar's day / month names                                |
+| `formatOptions` | `Intl.DateTimeFormatOptions` | `{ dateStyle: "medium" }` | Trigger text format                                                                                   |
+| `calendarProps` | `Partial<CalendarProps>`     | -                         | Anything else for the inner `Calendar` (class hooks, `view`, …), applied last                         |
+| `validate`      | `boolean \| ValidateOptions` | enabled                   | `false` disables the built-in guard; an object is merged with it (your validator runs after it)       |
+| `classInput`    | `string`                     | -                         | Trigger button classes                                                                                |
+| `classDialog`   | `string`                     | -                         | Dialog card classes                                                                                   |
+| `noScrollLock`  | `boolean`                    | `false`                   | Don't lock body scroll while the dialog is open                                                       |
+| `t`             | `TranslateFn`                | English                   | i18n — see the [Calendar README](../Calendar/README.md#i18n) (Slovak bundled: `CALENDAR_MESSAGES_SK`) |
+| `input`         | `HTMLInputElement`           | -                         | The (first) hidden input (bindable)                                                                   |
+
+Forwarded to the calendar unchanged (see its README): `min`, `max`, `isDateDisabled`,
+`weekStartsOn`, `weekendDays`, `zone`, `captionLayout`, `yearRange`, `showWeekNumbers`,
+`showOutsideDays`, `fixedWeeks`, `showToday`, `renderDay`. Plus the usual field props:
+`label`, `description`, `labelAfter`, `below`, `id`, `tabindex`, `renderSize`,
+`required`, `disabled`, `labelLeft*`, `style`, and the shared `InputWrapClassProps`.
+
+### Validation
+
+A hidden input is barred from native constraint validation, so both fields enforce
+everything in their own validator (default-on, like the other hidden-input fields):
+`required`, a valid ISO date, `min` / `max`, `isDateDisabled` — and the range field
+rejects a half range (a start without an end) **whether or not** it is `required`. The
+messages go through `t` and format the bound with the field's own display format
+("Date must be on or after Feb 5, 2026."). A consumer `customValidator` runs after the
+guard passes.
+
+Loose input is tolerated on the way in: `"2026-09-02T10:00:00Z"` or a `Date` are reduced
+to their calendar date (the date portion **as written**, never shifted through a zone).
+Unparseable input is displayed as empty but submitted as-is, so the validator flags it
+instead of silently posting an empty value.
+
+### Methods
+
+Accessed via a `bind:this` reference — the imperative validate API (`validate()`,
+`clearValidation()`, `getValidation()`, `focus()`, `scrollIntoView()`) plus `open()` /
+`close()` for the dialog (no-ops when `embedded`).
+
+### CSS Variables
+
+The calendar inside is styled by the `--stuic-calendar-*` tokens (see its README); the
+field shell adds:
+
+| Variable                              | Default                          | Description                          |
+| ------------------------------------- | -------------------------------- | ------------------------------------ |
+| `--stuic-field-date-icon-text`        | `--stuic-color-muted-foreground` | Trigger calendar icon color          |
+| `--stuic-field-date-placeholder-text` | `--stuic-input-placeholder`      | Trigger placeholder color            |
+| `--stuic-field-date-embedded-padding` | `0.5rem`                         | Padding around the embedded calendar |
+| `--stuic-field-date-dialog-padding`   | `1rem`                           | Dialog card padding                  |
+| `--stuic-field-date-dialog-radius`    | `--stuic-radius-container`       | Dialog card radius                   |
+| `--stuic-field-date-dialog-shadow`    | `--stuic-shadow-dialog`          | Dialog card shadow                   |
+
+The trigger follows the `--stuic-input-*` size tokens (`renderSize`), the dialog card the
+`--stuic-modal-dialog-bg` / `-text` tokens.
+
 ## 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.