compote-ui 0.72.1 → 0.74.1

package/dist/components/field/field.svelte

@@ -7,6 +7,8 @@
 		form,
 		field,
 		helperText,
+		errorText,
+		hideMessageLine = false,
 		class: className,
 		invalid,
 		required,
@@ -14,9 +16,15 @@
 		...rest
 	}: FieldRootProps = $props();
 
-	const isInvalid = $derived(form && field ? form.invalid(field) : (invalid ?? false));
+	// Declared before isInvalid, which reads it.
+	const resolvedError = $derived(
+		form && field ? (form.errors[field]?.[0] ?? null) : (errorText ?? null)
+	);
+	// An error that does not also mark the field invalid renders nothing at all:
+	// Ark's Field.ErrorText is gated on the field context's `invalid`. So a bare
+	// `errorText` implies it, while an explicit `invalid` still wins.
+	const isInvalid = $derived(form && field ? form.invalid(field) : (invalid ?? !!resolvedError));
 	const isRequired = $derived(form && field ? form.isRequired(field) : (required ?? false));
-	const errorText = $derived(form && field ? (form.errors[field]?.[0] ?? null) : null);
 </script>
 
 <Field.Root
@@ -26,9 +34,19 @@
 	class={cn('group flex flex-col gap-1.5', className)}
 >
 	{@render children?.()}
-	{#if errorText}
-		<Field.ErrorText>{errorText}</Field.ErrorText>
+	{#if resolvedError}
+		<Field.ErrorText>{resolvedError}</Field.ErrorText>
 	{:else if helperText}
 		<Field.HelperText>{helperText}</Field.HelperText>
+	{:else if !hideMessageLine}
+		<!--
+			Holds the message line open so a field does not change height when an
+			error appears. `1lh` resolves against this element's own line-height, so
+			it tracks the theme's font rather than assuming a pixel height. A plain
+			div and not an empty Field.HelperText: Ark gives that one an id which
+			aria-describedby points at, which would describe the control as having a
+			description that isn't there.
+		-->
+		<div class="h-lh text-xs" aria-hidden="true"></div>
 	{/if}
 </Field.Root>

package/dist/components/field/types.d.ts

@@ -11,6 +11,21 @@ export interface FieldRootProps extends FieldRootBaseProps {
     form?: FormAdapter;
     field?: string;
     helperText?: string;
+    /**
+     * Error to render below the control, for validation that does not go through
+     * a {@link FormAdapter} (e.g. a SvelteKit remote form's `field.issues()`).
+     * Passing it also marks the field invalid unless `invalid` is set explicitly.
+     * Ignored when `form` and `field` are given — the adapter wins, as it does
+     * for `invalid` and `required`.
+     */
+    errorText?: string | null;
+    /**
+     * Whether to drop the spacer that otherwise holds the message line open
+     * when there is no error or helper text to show. Defaults to `false`. Set
+     * to `true` for a field that never surfaces validation (a toolbar search
+     * box, say), so it doesn't reserve height it will never use.
+     */
+    hideMessageLine?: boolean;
 }
 export interface FieldLabelProps extends FieldLabelBaseProps {
     class?: ClassValue;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "compote-ui",
-	"version": "0.72.1",
+	"version": "0.74.1",
 	"license": "MIT",
 	"scripts": {
 		"dev": "vite dev --open",

package/skills/component-usage/references/forms-and-inputs.md

@@ -19,6 +19,32 @@ With a form adapter, `Field.Root` derives invalid/required state and renders the
 </Field.Root>
 ```
 
+`errorText` is the per-field route to that same line, for validation that doesn't fit the adapter's
+`Record<string, string[]>` shape — a SvelteKit remote form's `field.issues()`, say. **Passing it
+marks the field invalid**; an explicit `invalid` still wins, and the adapter wins over both.
+
+```svelte
+<Field.Root required errorText={fields.password.issues()?.[0]?.message}>
+	<PasswordInput label="Password" name={fields.password.as('password').name} />
+</Field.Root>
+```
+
+One message, not a list: several errors on one value are usually stages of the same judgement, and a
+stack that grows and shrinks per keystroke is what makes a form jump. Independent requirements (a
+password policy) belong in a persistent checklist shown from the start, not in error text. Where you
+genuinely need several, `<Field.ErrorText>` children still work.
+
+The message line is **always held open**, so a field never changes height when an error appears and
+nothing below it moves. Errors and `helperText` share that line — an error replaces the helper
+rather than stacking under it. For a field that never surfaces validation (a toolbar search box,
+say), pass `hideMessageLine` to drop the spacer entirely:
+
+```svelte
+<Field.Root hideMessageLine>
+	<Field.Input bind:value={search} placeholder="Search..." />
+</Field.Root>
+```
+
 List controls use `{ value, label }` items:
 
 ```svelte