@ternkit/tern 1.3.0 → 1.5.0

package/dist/ui/Empty.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from 'svelte';
+type Props = {
+    title: string;
+    description?: string;
+    /** The heading level, to fit the page's outline. */
+    level?: 2 | 3 | 4;
+    /** An illustration or icon above the title. */
+    icon?: Snippet;
+    /** What to do next, such as a Create button. */
+    actions?: Snippet;
+    class?: string;
+};
+declare const Empty: import("svelte").Component<Props, {}, "">;
+type Empty = ReturnType<typeof Empty>;
+export default Empty;

package/dist/ui/Field.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import { setField } from './field.js';
+	import { getForm } from './form.js';
 
 	type Props = {
 		/** The visible label. */
@@ -11,16 +12,24 @@
 		error?: string | null;
 		required?: boolean;
 		disabled?: boolean;
+		/** The control's name. Inside a Form, the Field shows that field's error and knows if it's required, and the control posts under it. */
+		name?: string;
 		class?: string;
 		/** The control, such as an Input, Textarea or Select. */
 		children: Snippet;
 	};
-	let { label, description, error = null, required = false, disabled = false, class: klass = '', children }: Props = $props();
+	let { label, description, error: errorProp = null, required: requiredProp = false, disabled = false, name, class: klass = '', children }: Props = $props();
+
+	const form = getForm();
+	const error = $derived(errorProp ?? (name ? form?.error(name) : undefined) ?? null);
+	const required = $derived(requiredProp || (name ? !!form?.field(name)?.required : false));
 
 	const uid = $props.id();
+	let custom = $state(false);
 	const id = `tern-field-${uid}`;
 	setField({
 		id,
+		labelId: `${id}-label`,
 		get describedBy() {
 			return [description ? `${id}-description` : '', error ? `${id}-error` : ''].filter(Boolean).join(' ') || undefined;
 		},
@@ -32,12 +41,22 @@
 		},
 		get disabled() {
 			return disabled;
+		},
+		custom() {
+			custom = true;
+		},
+		get name() {
+			return name;
+		},
+		get value() {
+			return name && !form?.field(name)?.secret ? form?.value(name) : undefined;
 		}
 	});
 </script>
 
 <div class="tern-field {klass}" class:disabled>
-	<label for={id}>
+	<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions -->
+	<label for={custom ? undefined : id} id="{id}-label" onclick={custom ? () => document.getElementById(id)?.focus() : undefined}>
 		{label}
 		{#if required}<span class="required" aria-hidden="true">*</span>{/if}
 	</label>
@@ -49,6 +68,7 @@
 <style>
 	.tern-field {
 		display: grid;
+		align-content: start;
 		gap: 0.375rem;
 	}
 	label {

package/dist/ui/Field.svelte.d.ts

@@ -8,6 +8,8 @@ type Props = {
     error?: string | null;
     required?: boolean;
     disabled?: boolean;
+    /** The control's name. Inside a Form, the Field shows that field's error and knows if it's required, and the control posts under it. */
+    name?: string;
     class?: string;
     /** The control, such as an Input, Textarea or Select. */
     children: Snippet;

package/dist/ui/Form.svelte

@@ -0,0 +1,159 @@
+<script lang="ts">
+	import { tick, type Snippet } from 'svelte';
+	import type { HTMLFormAttributes } from 'svelte/elements';
+	import { enhance as enhanceAction } from '../runtime/forms.js';
+	import { validate, type FormField } from '../runtime/validate.js';
+	import Alert from './Alert.svelte';
+	import { setForm } from './form.js';
+
+	type Failure = { errors?: Record<string, string>; values?: Record<string, unknown>; message?: string };
+
+	type Props = Omit<HTMLFormAttributes, 'onsubmit'> & {
+		/** The action's rules, from ./$forms: forms.create. The browser checks them as the user types and before posting. */
+		rules?: FormField[];
+		/** The page's form prop, so the server's errors and the posted values show up. */
+		form?: unknown;
+		/** Post in the background with use:enhance. Without it, or without JavaScript, the browser posts the form. */
+		enhance?: boolean;
+		/** Whether a post is in flight; bind it to show a spinner. */
+		submitting?: boolean;
+		/** Clear the form after a successful post. */
+		reset?: boolean;
+		/** Runs after a successful post with the action's result. */
+		onsuccess?: (data: unknown) => void;
+		children: Snippet;
+	};
+	let { rules = [], form, enhance = true, submitting = $bindable(false), reset = true, onsuccess, method = 'POST', children, class: klass = '', ...rest }: Props = $props();
+
+	const uid = $props.id();
+	let el = $state<HTMLFormElement>();
+	let client = $state<Record<string, string>>({});
+	let touched = $state<Record<string, boolean>>({});
+	let edited = $state<Record<string, boolean>>({});
+	let submitted = $state(false);
+	let hydrated = $state(false);
+	let summary = $state('');
+
+	const failure = $derived((form && typeof form === 'object' && 'errors' in form ? form : null) as Failure | null);
+	// A new answer from the server replaces what the user had edited since the last one.
+	$effect(() => {
+		void failure;
+		edited = {};
+	});
+	$effect(() => {
+		hydrated = true;
+	});
+
+	const byName = $derived(new Map(rules.map((f) => [f.name, f])));
+	setForm({
+		error: (name) => client[name] ?? (edited[name] ? undefined : failure?.errors?.[name]),
+		value: (name) => {
+			const v = failure?.values?.[name];
+			return typeof v === 'string' ? v : undefined;
+		},
+		field: (name) => byName.get(name)
+	});
+
+	function check(names: string[]) {
+		if (!el || rules.length === 0) return;
+		const all = validate(rules, new FormData(el));
+		const next = { ...client };
+		for (const n of names) {
+			if (all[n]) next[n] = all[n]!;
+			else delete next[n];
+		}
+		client = next;
+	}
+	// A field and the fields that must match it, such as a password and its confirmation.
+	const related = (name: string) => [name, ...rules.filter((f) => f.rules?.some((r) => r.name === 'same' && r.arg === name)).map((f) => f.name)];
+
+	function oninput(e: Event) {
+		const name = (e.target as HTMLInputElement | null)?.name;
+		if (!name) return;
+		edited = { ...edited, [name]: true };
+		if (touched[name] || submitted) check(related(name).filter((n) => touched[n] || submitted || n === name));
+	}
+	function onfocusout(e: FocusEvent) {
+		const name = (e.target as HTMLInputElement | null)?.name;
+		// Don't complain about a field the user only passed through.
+		if (!name || !byName.has(name) || (!edited[name] && !submitted)) return;
+		touched = { ...touched, [name]: true };
+		check([name]);
+	}
+
+	/** Checks everything; returns false and focuses the first problem if anything is wrong. */
+	function checkAll(data: FormData) {
+		submitted = true;
+		const errors = validate(rules, data) as Record<string, string>;
+		client = errors;
+		const names = Object.keys(errors);
+		if (names.length === 0) {
+			summary = '';
+			return true;
+		}
+		summary = names.length === 1 ? '1 field needs attention.' : `${names.length} fields need attention.`;
+		void tick().then(() => el?.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus());
+		return false;
+	}
+
+	const submit = ({ formData, cancel }: { formData: FormData; cancel(): void }) => {
+		const errors = validate(rules, formData);
+		if (Object.keys(errors).length > 0) {
+			cancel();
+			checkAll(formData);
+			return;
+		}
+		submitted = true;
+		client = {};
+		summary = '';
+		submitting = true;
+		return async ({ update, result }: { update: (o?: { reset?: boolean }) => Promise<void>; result: { type: string; data?: unknown } }) => {
+			await update({ reset });
+			submitting = false;
+			if (result.type === 'success') {
+				submitted = false;
+				touched = {};
+				onsuccess?.(result.data);
+			} else if (result.type === 'failure') {
+				await tick();
+				el?.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus();
+			}
+		};
+	};
+
+	function attach(node: HTMLFormElement) {
+		if (!enhance) return;
+		const action = enhanceAction(node, submit as never);
+		return () => action?.destroy?.();
+	}
+</script>
+
+<form
+	bind:this={el}
+	class="tern-form {klass}"
+	{method}
+	novalidate={hydrated && rules.length > 0}
+	aria-describedby={failure?.message ? `tern-form-${uid}-message` : undefined}
+	{...rest}
+	{oninput}
+	onchange={oninput}
+	{onfocusout}
+	onsubmit={(e) => {
+		if (enhance) return; // use:enhance checks first
+		if (!checkAll(new FormData(e.currentTarget))) e.preventDefault();
+	}}
+	{@attach attach}
+>
+	{#if failure?.message}
+		<div id="tern-form-{uid}-message"><Alert tone="danger" live>{failure.message}</Alert></div>
+	{/if}
+	{@render children()}
+	<p class="tern-sr-only" role="status">{summary}</p>
+</form>
+
+<style>
+	.tern-form {
+		display: grid;
+		gap: 1rem;
+	}
+</style>

package/dist/ui/Form.svelte.d.ts

@@ -0,0 +1,21 @@
+import { type Snippet } from 'svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
+import { type FormField } from '../runtime/validate.js';
+type Props = Omit<HTMLFormAttributes, 'onsubmit'> & {
+    /** The action's rules, from ./$forms: forms.create. The browser checks them as the user types and before posting. */
+    rules?: FormField[];
+    /** The page's form prop, so the server's errors and the posted values show up. */
+    form?: unknown;
+    /** Post in the background with use:enhance. Without it, or without JavaScript, the browser posts the form. */
+    enhance?: boolean;
+    /** Whether a post is in flight; bind it to show a spinner. */
+    submitting?: boolean;
+    /** Clear the form after a successful post. */
+    reset?: boolean;
+    /** Runs after a successful post with the action's result. */
+    onsuccess?: (data: unknown) => void;
+    children: Snippet;
+};
+declare const Form: import("svelte").Component<Props, {}, "submitting">;
+type Form = ReturnType<typeof Form>;
+export default Form;

package/dist/ui/HoverCard.svelte

@@ -0,0 +1,106 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { float, type Align, type Side } from './floating.js';
+
+	export type HoverCardTrigger = {
+		'aria-describedby'?: string;
+		onpointerenter: () => void;
+		onpointerleave: () => void;
+		onfocus: () => void;
+		onblur: () => void;
+		onkeydown: (e: KeyboardEvent) => void;
+	};
+
+	type Props = {
+		/** The link or button it previews. Spread the props onto it. */
+		trigger: Snippet<[HoverCardTrigger]>;
+		/** The preview. Pointer and keyboard users see it; it is also linked as the trigger's description, so keep it short or make sure what it shows is reachable elsewhere. */
+		children: Snippet;
+		side?: Side;
+		align?: Align;
+		/** Milliseconds before it opens. */
+		openDelay?: number;
+		/** Milliseconds before it closes once the pointer leaves. */
+		closeDelay?: number;
+		class?: string;
+	};
+	let { trigger, children, side = 'bottom', align = 'center', openDelay = 500, closeDelay = 200, class: klass = '' }: Props = $props();
+
+	const uid = $props.id();
+	const id = `tern-hovercard-${uid}`;
+	let open = $state(false);
+	let card = $state<HTMLDivElement>();
+	let anchorEl: Element | null = null;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+
+	function later(fn: () => void, ms: number) {
+		clearTimeout(timer);
+		timer = setTimeout(fn, ms);
+	}
+	const show = (now = false) => {
+		anchorEl = document.activeElement?.matches(`[aria-describedby~="${id}"]`) ? document.activeElement : (document.querySelector(`[aria-describedby~="${id}"]`) ?? anchorEl);
+		if (now) {
+			clearTimeout(timer);
+			open = true;
+		} else later(() => (open = true), openDelay);
+	};
+	const hide = (now = false) => (now ? ((open = false), clearTimeout(timer)) : later(() => (open = false), closeDelay));
+
+	$effect(() => {
+		if (!open || !card || !anchorEl) return;
+		card.showPopover?.();
+		return float(card, anchorEl, { side, align, offset: 8 });
+	});
+</script>
+
+{@render trigger({
+	'aria-describedby': id,
+	onpointerenter: () => show(),
+	onpointerleave: () => hide(),
+	onfocus: () => show(true),
+	onblur: () => hide(true),
+	onkeydown: (e) => e.key === 'Escape' && hide(true)
+})}
+<div
+	bind:this={card}
+	{id}
+	class="tern-hovercard {klass}"
+	class:open
+	popover="manual"
+	role="none"
+	onpointerenter={() => clearTimeout(timer)}
+	onpointerleave={() => hide()}
+>
+	{#if open}{@render children()}{/if}
+</div>
+
+<style>
+	.tern-hovercard {
+		width: max-content;
+		max-width: min(20rem, calc(100vw - 1rem));
+		padding: 1rem;
+		color: var(--tern-fg);
+		background: var(--tern-surface);
+		border: 1px solid var(--tern-border);
+		border-radius: var(--tern-radius);
+		box-shadow: var(--tern-shadow-lg);
+		font-size: 0.875rem;
+	}
+	.tern-hovercard:not(.open) {
+		display: none;
+	}
+	.open {
+		animation: tern-hover-in var(--tern-duration) ease-out;
+	}
+	@keyframes tern-hover-in {
+		from {
+			opacity: 0;
+			transform: translateY(2px);
+		}
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.open {
+			animation: none;
+		}
+	}
+</style>

package/dist/ui/HoverCard.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+import { type Align, type Side } from './floating.js';
+export type HoverCardTrigger = {
+    'aria-describedby'?: string;
+    onpointerenter: () => void;
+    onpointerleave: () => void;
+    onfocus: () => void;
+    onblur: () => void;
+    onkeydown: (e: KeyboardEvent) => void;
+};
+type Props = {
+    /** The link or button it previews. Spread the props onto it. */
+    trigger: Snippet<[HoverCardTrigger]>;
+    /** The preview. Pointer and keyboard users see it; it is also linked as the trigger's description, so keep it short or make sure what it shows is reachable elsewhere. */
+    children: Snippet;
+    side?: Side;
+    align?: Align;
+    /** Milliseconds before it opens. */
+    openDelay?: number;
+    /** Milliseconds before it closes once the pointer leaves. */
+    closeDelay?: number;
+    class?: string;
+};
+declare const HoverCard: import("svelte").Component<Props, {}, "">;
+type HoverCard = ReturnType<typeof HoverCard>;
+export default HoverCard;

package/dist/ui/Input.svelte

@@ -3,8 +3,8 @@
 	import { getField } from './field.js';
 
 	type Props = HTMLInputAttributes & { value?: unknown };
-	let { value = $bindable(), class: klass = '', ...rest }: Props = $props();
 	const field = getField();
+	let { value = $bindable(field?.value), class: klass = '', ...rest }: Props = $props();
 </script>
 
 <input
@@ -14,6 +14,7 @@
 	aria-invalid={field?.invalid || undefined}
 	required={field?.required}
 	disabled={field?.disabled}
+	name={field?.name}
 	{...rest}
 	bind:value
 />

package/dist/ui/InputGroup.svelte

@@ -0,0 +1,80 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	type Props = {
+		/** Before the input: text such as "https://", an icon, or a button. */
+		start?: Snippet;
+		/** After the input: text such as ".com", a unit, or a button. */
+		end?: Snippet;
+		class?: string;
+		/** The Input. */
+		children: Snippet;
+	};
+	let { start, end, class: klass = '', children }: Props = $props();
+</script>
+
+<!-- An Input with text, icons or buttons inside its border. Text in start and end is read with the label when you add it to the Field's description, not on its own. -->
+<div class="tern-input-group {klass}">
+	{#if start}<span class="addon start">{@render start()}</span>{/if}
+	{@render children()}
+	{#if end}<span class="addon end">{@render end()}</span>{/if}
+</div>
+
+<style>
+	.tern-input-group {
+		display: flex;
+		align-items: center;
+		height: var(--tern-control-height);
+		background: var(--tern-surface);
+		border: 1px solid var(--tern-border-strong);
+		border-radius: var(--tern-radius-sm);
+		transition:
+			border-color var(--tern-duration),
+			box-shadow var(--tern-duration);
+	}
+	.tern-input-group:hover {
+		border-color: var(--tern-muted);
+	}
+	.tern-input-group:has(:global(input:focus-visible)) {
+		border-color: var(--tern-accent);
+		box-shadow: 0 0 0 3px color-mix(in oklch, var(--tern-ring) 30%, transparent);
+	}
+	.tern-input-group:has(:global([aria-invalid='true'])) {
+		border-color: var(--tern-danger);
+	}
+	.tern-input-group > :global(.tern-input) {
+		flex: 1;
+		min-width: 0;
+		height: 100%;
+		border: 0;
+		box-shadow: none;
+		background: transparent;
+	}
+	.tern-input-group > :global(.tern-input:focus-visible) {
+		box-shadow: none;
+	}
+	.addon {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.25rem;
+		height: 100%;
+		color: var(--tern-muted);
+		font-size: 0.875rem;
+		white-space: nowrap;
+	}
+	.start {
+		padding-inline-start: 0.75rem;
+	}
+	.end {
+		padding-inline-end: 0.75rem;
+	}
+	.start + :global(.tern-input) {
+		padding-inline-start: 0.4rem;
+	}
+	.addon :global(.tern-btn) {
+		height: calc(var(--tern-control-height) - 0.6rem);
+	}
+	.end:has(:global(.tern-btn)) {
+		padding-inline-end: 0.25rem;
+	}
+</style>

package/dist/ui/InputGroup.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+type Props = {
+    /** Before the input: text such as "https://", an icon, or a button. */
+    start?: Snippet;
+    /** After the input: text such as ".com", a unit, or a button. */
+    end?: Snippet;
+    class?: string;
+    /** The Input. */
+    children: Snippet;
+};
+declare const InputGroup: import("svelte").Component<Props, {}, "">;
+type InputGroup = ReturnType<typeof InputGroup>;
+export default InputGroup;

package/dist/ui/InputOTP.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+	import { getField } from './field.js';
+
+	type Props = {
+		/** The code; bind it. */
+		value?: string;
+		/** How many characters. */
+		length?: number;
+		/** numeric for digits only, or alphanumeric. */
+		mode?: 'numeric' | 'alphanumeric';
+		/** Labels it when it isn't in a Field. */
+		label?: string;
+		name?: string;
+		disabled?: boolean;
+		class?: string;
+		/** Runs once every character is entered, such as to submit. */
+		oncomplete?: (code: string) => void;
+	};
+	const field = getField();
+	let { value = $bindable(field?.value ?? ''), length = 6, mode = 'numeric', label, name: nameProp, disabled = false, class: klass = '', oncomplete }: Props = $props();
+	const name = $derived(nameProp ?? field?.name);
+
+	let input = $state<HTMLInputElement>();
+	let focused = $state(false);
+	let caret = $state(0);
+	const pattern = $derived(mode === 'numeric' ? /[^0-9]/g : /[^0-9a-z]/gi);
+
+	function oninput() {
+		const clean = input!.value.replace(pattern, '').slice(0, length);
+		input!.value = clean;
+		value = clean;
+		caret = clean.length;
+		if (clean.length === length) oncomplete?.(clean);
+	}
+</script>
+
+<!-- One real input, drawn as boxes: pasting, autofill from SMS and screen readers all just work. -->
+<div class="tern-otp {klass}" class:focused class:disabled={disabled || field?.disabled} style:--length={length}>
+	<input
+		bind:this={input}
+		{value}
+		{name}
+		id={field?.id}
+		aria-label={field ? undefined : label}
+		aria-describedby={field?.describedBy}
+		aria-invalid={field?.invalid || undefined}
+		required={field?.required}
+		disabled={disabled || field?.disabled}
+		inputmode={mode === 'numeric' ? 'numeric' : 'text'}
+		autocomplete="one-time-code"
+		autocapitalize="characters"
+		spellcheck="false"
+		pattern={mode === 'numeric' ? `[0-9]{${length}}` : `[0-9A-Za-z]{${length}}`}
+		{oninput}
+		onfocus={() => {
+			focused = true;
+			caret = value.length;
+		}}
+		onblur={() => (focused = false)}
+		onselect={() => (caret = Math.min(input?.selectionStart ?? 0, length - 1))}
+	/>
+	<div class="boxes" aria-hidden="true">
+		{#each { length }, i (i)}
+			<span class="box" class:active={focused && i === Math.min(caret, length - 1)} class:filled={i < value.length}>
+				{value[i] ?? ''}
+				{#if focused && i === value.length}<span class="caret"></span>{/if}
+			</span>
+		{/each}
+	</div>
+</div>
+
+<style>
+	.tern-otp {
+		position: relative;
+		width: fit-content;
+	}
+	input {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		opacity: 0;
+		font-size: 16px; /* no zoom on iOS */
+		letter-spacing: 2.6rem;
+		caret-color: transparent;
+		border: 0;
+		padding: 0;
+		cursor: text;
+		z-index: 1;
+	}
+	.boxes {
+		display: flex;
+		gap: 0.5rem;
+	}
+	.box {
+		position: relative;
+		display: grid;
+		place-items: center;
+		width: 2.5rem;
+		height: 2.875rem;
+		font-family: var(--tern-font-mono);
+		font-size: 1.25rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		color: var(--tern-fg);
+		background: var(--tern-surface);
+		border: 1px solid var(--tern-border-strong);
+		border-radius: var(--tern-radius-sm);
+		transition:
+			border-color var(--tern-duration),
+			box-shadow var(--tern-duration);
+	}
+	.box.active {
+		border-color: var(--tern-accent);
+		box-shadow: 0 0 0 3px color-mix(in oklch, var(--tern-ring) 30%, transparent);
+	}
+	.caret {
+		position: absolute;
+		width: 1px;
+		height: 1.25rem;
+		background: var(--tern-fg);
+		animation: blink 1s steps(1) infinite;
+	}
+	.tern-otp:has(input[aria-invalid='true']) .box {
+		border-color: var(--tern-danger);
+	}
+	.disabled {
+		opacity: 0.6;
+	}
+	@keyframes blink {
+		50% {
+			opacity: 0;
+		}
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.caret {
+			animation: none;
+		}
+	}
+</style>

package/dist/ui/InputOTP.svelte.d.ts

@@ -0,0 +1,18 @@
+type Props = {
+    /** The code; bind it. */
+    value?: string;
+    /** How many characters. */
+    length?: number;
+    /** numeric for digits only, or alphanumeric. */
+    mode?: 'numeric' | 'alphanumeric';
+    /** Labels it when it isn't in a Field. */
+    label?: string;
+    name?: string;
+    disabled?: boolean;
+    class?: string;
+    /** Runs once every character is entered, such as to submit. */
+    oncomplete?: (code: string) => void;
+};
+declare const InputOTP: import("svelte").Component<Props, {}, "value">;
+type InputOTP = ReturnType<typeof InputOTP>;
+export default InputOTP;