@ternkit/tern 1.2.1 → 1.4.0

package/dist/ui/Empty.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+	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;
+	};
+	let { title, description, level = 3, icon, actions, class: klass = '' }: Props = $props();
+</script>
+
+<!-- What a list or page shows when it has nothing yet: what it is for and what to do. -->
+<div class="tern-empty {klass}">
+	{#if icon}<div class="icon" aria-hidden="true">{@render icon()}</div>{/if}
+	<svelte:element this={`h${level}`} class="title">{title}</svelte:element>
+	{#if description}<p>{description}</p>{/if}
+	{#if actions}<div class="actions">{@render actions()}</div>{/if}
+</div>
+
+<style>
+	.tern-empty {
+		display: grid;
+		justify-items: center;
+		gap: 0.5rem;
+		padding: 2.5rem 1.5rem;
+		text-align: center;
+		border: 1px dashed var(--tern-border-strong);
+		border-radius: var(--tern-radius);
+	}
+	.icon {
+		display: grid;
+		place-items: center;
+		width: 2.75rem;
+		height: 2.75rem;
+		margin-bottom: 0.25rem;
+		color: var(--tern-accent);
+		background: var(--tern-accent-soft);
+		border-radius: 50%;
+	}
+	.title {
+		margin: 0;
+		font-size: 1rem;
+		font-weight: 600;
+	}
+	p {
+		max-width: 28rem;
+		margin: 0;
+		color: var(--tern-muted);
+		font-size: 0.875rem;
+	}
+	.actions {
+		display: flex;
+		gap: 0.5rem;
+		margin-top: 0.5rem;
+	}
+</style>

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

@@ -0,0 +1,97 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { setField } from './field.js';
+	import { getForm } from './form.js';
+
+	type Props = {
+		/** The visible label. */
+		label: string;
+		/** Help text under the control, read by screen readers with it. */
+		description?: string;
+		/** An error message; marks the control invalid and announces the message. */
+		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: 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;
+		},
+		get invalid() {
+			return !!error;
+		},
+		get required() {
+			return required;
+		},
+		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>
+	<!-- 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>
+	{@render children()}
+	{#if description}<p class="description" id="{id}-description">{description}</p>{/if}
+	{#if error}<p class="error" id="{id}-error" role="alert">{error}</p>{/if}
+</div>
+
+<style>
+	.tern-field {
+		display: grid;
+		align-content: start;
+		gap: 0.375rem;
+	}
+	label {
+		font-size: 0.875rem;
+		font-weight: 550;
+		color: var(--tern-fg);
+	}
+	.required {
+		color: var(--tern-danger);
+		margin-inline-start: 0.125rem;
+	}
+	.description {
+		margin: 0;
+		font-size: 0.8125rem;
+		color: var(--tern-muted);
+	}
+	.error {
+		margin: 0;
+		font-size: 0.8125rem;
+		color: var(--tern-danger);
+		font-weight: 500;
+	}
+	.disabled label {
+		opacity: 0.6;
+	}
+</style>

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

@@ -0,0 +1,19 @@
+import type { Snippet } from 'svelte';
+type Props = {
+    /** The visible label. */
+    label: string;
+    /** Help text under the control, read by screen readers with it. */
+    description?: string;
+    /** An error message; marks the control invalid and announces the message. */
+    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;
+};
+declare const Field: import("svelte").Component<Props, {}, "">;
+type Field = ReturnType<typeof Field>;
+export default Field;

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

@@ -0,0 +1,62 @@
+<script lang="ts">
+	import type { HTMLInputAttributes } from 'svelte/elements';
+	import { getField } from './field.js';
+
+	type Props = HTMLInputAttributes & { value?: unknown };
+	const field = getField();
+	let { value = $bindable(field?.value), class: klass = '', ...rest }: Props = $props();
+</script>
+
+<input
+	class="tern-input {klass}"
+	id={field?.id}
+	aria-describedby={field?.describedBy}
+	aria-invalid={field?.invalid || undefined}
+	required={field?.required}
+	disabled={field?.disabled}
+	name={field?.name}
+	{...rest}
+	bind:value
+/>
+
+<style>
+	.tern-input {
+		width: 100%;
+		box-sizing: border-box;
+		height: var(--tern-control-height);
+		padding: 0 0.75rem;
+		font: inherit;
+		font-size: 0.875rem;
+		color: var(--tern-fg);
+		background: var(--tern-surface);
+		border: 1px solid var(--tern-border-strong);
+		border-radius: var(--tern-radius-sm);
+		box-shadow: inset 0 1px 1px oklch(0.24 0.02 240 / 0.04);
+		transition:
+			border-color var(--tern-duration),
+			box-shadow var(--tern-duration);
+	}
+	.tern-input::placeholder {
+		color: var(--tern-muted);
+		opacity: 0.8;
+	}
+	.tern-input:hover:not(:disabled) {
+		border-color: var(--tern-muted);
+	}
+	.tern-input:focus-visible {
+		outline: none;
+		border-color: var(--tern-accent);
+		box-shadow: 0 0 0 3px color-mix(in oklch, var(--tern-ring) 30%, transparent);
+	}
+	.tern-input[aria-invalid='true'] {
+		border-color: var(--tern-danger);
+	}
+	.tern-input[aria-invalid='true']:focus-visible {
+		box-shadow: 0 0 0 3px color-mix(in oklch, var(--tern-danger) 25%, transparent);
+	}
+	.tern-input:disabled {
+		opacity: 0.6;
+		cursor: not-allowed;
+		background: var(--tern-surface-2);
+	}
+</style>

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

@@ -0,0 +1,7 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+type Props = HTMLInputAttributes & {
+    value?: unknown;
+};
+declare const Input: import("svelte").Component<Props, {}, "value">;
+type Input = ReturnType<typeof Input>;
+export default Input;

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;