@mystravil/hardpoint 0.1.0 → 0.2.0

package/dist/components/CheckboxGroup.svelte

@@ -8,58 +8,119 @@
 		label: string;
 		/** A second line in `--muted` under the label. */
 		hint?: string;
+		/** A Tag after the label, such as "Recommended": a short fixed string, set in caps. */
+		tag?: string;
 		disabled?: boolean;
 	};
 
+	/** The group's name: a fixed caps `label`, or a `legend` set as written. Exactly one. */
+	type CheckboxGroupName =
+		| {
+				/** The caps label that names the group: a fixed string the app defines. */
+				label: string;
+				legend?: never;
+		  }
+		| {
+				label?: never;
+				/**
+				 * The group's name as content, set as written in 16px at weight 500:
+				 * a question, or a name with a counter before it.
+				 */
+				legend: Snippet;
+		  };
+
 	/** Attributes and handlers not listed here go to the group element. */
-	export type CheckboxGroupProps = Omit<CheckboxPrimitive.GroupProps, 'child' | 'children' | 'ref'> & {
-		/** The caps label that names the group. */
-		label: string;
-		/** A line in `--muted` under the label, read out as the group's description. */
-		hint?: string;
-		/** The choices. Without it, pass `Checkbox` components with a `value` as children. */
-		items?: CheckboxGroupItem[];
-		children?: Snippet;
-		/** The group element. */
-		ref?: HTMLElement | null;
-	};
+	export type CheckboxGroupProps = Omit<CheckboxPrimitive.GroupProps, 'child' | 'children' | 'ref'> &
+		CheckboxGroupName & {
+			/** A line in `--muted` under the name, read out as the group's description. */
+			hint?: string;
+			/**
+			 * The error to show under the boxes, with an icon, linked by
+			 * `aria-describedby`; it sets `aria-invalid` on the group. Say how to
+			 * fix the problem. The app validates; the group shows what it is given.
+			 */
+			error?: string;
+			/** The choices. Without it, pass `Checkbox` components with a `value` as children. */
+			items?: CheckboxGroupItem[];
+			children?: Snippet;
+			/** The group element. */
+			ref?: HTMLElement | null;
+		};
 </script>
 
 <script lang="ts">
+	import { untrack } from 'svelte';
 	import { Checkbox as BitsCheckbox } from 'bits-ui';
 	import Checkbox from './Checkbox.svelte';
+	import { fadeIn } from './internal/fade-in.js';
 
 	const uid = $props.id();
 
 	let {
 		value = $bindable([]),
 		label,
+		legend,
 		hint,
+		error,
 		items,
 		id = uid,
 		ref = $bindable(null),
 		class: className,
 		'aria-describedby': describedBy,
+		'aria-invalid': ariaInvalid,
 		children,
 		...rest
 	}: CheckboxGroupProps = $props();
 
 	const hintId = $derived(`${id}-hint`);
-	const describedByIds = $derived([hint ? hintId : null, describedBy].filter(Boolean).join(' ') || undefined);
+	const errorId = $derived(`${id}-error`);
+	// The error first, so a screen reader reads it before the hint.
+	const describedByIds = $derived(
+		[error ? errorId : undefined, hint ? hintId : undefined, describedBy].filter(Boolean).join(' ') ||
+			undefined
+	);
+
+	// ---- Short motion: the error (BRIEF, --dur-message) ---------------------
+
+	// As in TextField: an error that appears after the first render fades in
+	// from 0 over --dur-message; one that clears goes at once; a group that
+	// renders with an error shows it at once.
+	let errorShown = untrack(() => !!error);
+	$effect(() => {
+		const shown = !!error;
+		untrack(() => {
+			const appeared = shown && !errorShown;
+			errorShown = shown;
+			const message = appeared ? ref?.querySelector(':scope > .error') : null;
+			if (message) fadeIn(message, '--dur-message');
+		});
+	});
 </script>
 
 <!--
-	Several independent choices under one caps label: a Bits UI Checkbox.Group,
-	a role="group" element named by the label. `bind:value` holds the values of
-	the checked boxes. `disabled`, `required`, `readonly` and `name` apply to
-	every box. Attributes, handlers and `class` go to the group element.
+	Several independent choices under one name: a Bits UI Checkbox.Group, a
+	role="group" element named by its caps `label` or its `legend`.
+	`bind:value` holds the values of the checked boxes. `disabled`,
+	`required`, `readonly` and `name` apply to every box. Attributes, handlers
+	and `class` go to the group element.
 -->
-<BitsCheckbox.Group bind:value bind:ref {id} aria-describedby={describedByIds} {...rest}>
+<BitsCheckbox.Group
+	bind:value
+	bind:ref
+	{id}
+	aria-describedby={describedByIds}
+	aria-invalid={error ? true : ariaInvalid}
+	{...rest}
+>
 	{#snippet child({ props })}
-		<div {...props} class={['hp-checkbox-group', className]}>
+		<div {...props} class={['hp-checkbox-group', className]} data-invalid={error ? '' : undefined}>
 			<BitsCheckbox.GroupLabel>
 				{#snippet child({ props: labelProps })}
-					<span {...labelProps} class="hp-label group-label">{label}</span>
+					{#if legend}
+						<div {...labelProps} class="legend">{@render legend()}</div>
+					{:else}
+						<span {...labelProps} class="hp-label group-label">{label}</span>
+					{/if}
 				{/snippet}
 			</BitsCheckbox.GroupLabel>
 			{#if hint}
@@ -68,20 +129,37 @@
 			<div class="items">
 				{#if items}
 					{#each items as item (item.value)}
-						<Checkbox value={item.value} label={item.label} hint={item.hint} disabled={item.disabled} />
+						<Checkbox
+							value={item.value}
+							label={item.label}
+							tag={item.tag}
+							hint={item.hint}
+							disabled={item.disabled}
+						/>
 					{/each}
 				{:else}
 					{@render children?.()}
 				{/if}
 			</div>
+			{#if error}
+				<p class="error hp-caption" id={errorId}>
+					<span class="icon" aria-hidden="true">
+						<svg viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor">
+							<path d="M1.5 1.5h13v13h-13z" />
+							<path d="M8 4v4M8 10v2" stroke-width="2" />
+						</svg>
+					</span>
+					<span>{error}</span>
+				</p>
+			{/if}
 		</div>
 	{/snippet}
 </BitsCheckbox.Group>
 
 <style>
-	/* The caps label, its hint, then the boxes, 8px apart so neighbouring
-	   targets never touch. Rows keep their own height when a layout makes
-	   the group taller. */
+	/* The name, its hint, then the boxes, 8px apart so neighbouring targets
+	   never touch, then the error. Rows keep their own height when a layout
+	   makes the group taller. */
 	.hp-checkbox-group {
 		display: grid;
 		align-content: start;
@@ -92,8 +170,38 @@
 	.hint {
 		color: var(--muted);
 	}
+	/* A name set as written: a question, or a name with a counter. */
+	.legend {
+		font-size: var(--type-body);
+		font-weight: 500;
+		line-height: 24px;
+	}
+	[data-disabled] > .legend {
+		color: var(--muted);
+	}
 	.items {
 		display: grid;
 		gap: var(--space-2);
 	}
+
+	/* ---- The error: TextField's ------------------------------------------- */
+
+	/* It starts 8px under the last box's row, clear of its focus contour. */
+	.error {
+		display: flex;
+		gap: var(--space-2);
+		margin-top: var(--space-1);
+		color: var(--danger);
+	}
+	/* One line box high, so the icon centres on the first line of the
+	   message however it wraps. */
+	.icon {
+		display: flex;
+		flex: none;
+		align-items: center;
+		height: 1lh;
+	}
+	.icon svg {
+		display: block;
+	}
 </style>

package/dist/components/CheckboxGroup.svelte.d.ts

@@ -6,14 +6,33 @@ export type CheckboxGroupItem = {
     label: string;
     /** A second line in `--muted` under the label. */
     hint?: string;
+    /** A Tag after the label, such as "Recommended": a short fixed string, set in caps. */
+    tag?: string;
     disabled?: boolean;
 };
-/** Attributes and handlers not listed here go to the group element. */
-export type CheckboxGroupProps = Omit<CheckboxPrimitive.GroupProps, 'child' | 'children' | 'ref'> & {
-    /** The caps label that names the group. */
+/** The group's name: a fixed caps `label`, or a `legend` set as written. Exactly one. */
+type CheckboxGroupName = {
+    /** The caps label that names the group: a fixed string the app defines. */
     label: string;
-    /** A line in `--muted` under the label, read out as the group's description. */
+    legend?: never;
+} | {
+    label?: never;
+    /**
+     * The group's name as content, set as written in 16px at weight 500:
+     * a question, or a name with a counter before it.
+     */
+    legend: Snippet;
+};
+/** Attributes and handlers not listed here go to the group element. */
+export type CheckboxGroupProps = Omit<CheckboxPrimitive.GroupProps, 'child' | 'children' | 'ref'> & CheckboxGroupName & {
+    /** A line in `--muted` under the name, read out as the group's description. */
     hint?: string;
+    /**
+     * The error to show under the boxes, with an icon, linked by
+     * `aria-describedby`; it sets `aria-invalid` on the group. Say how to
+     * fix the problem. The app validates; the group shows what it is given.
+     */
+    error?: string;
     /** The choices. Without it, pass `Checkbox` components with a `value` as children. */
     items?: CheckboxGroupItem[];
     children?: Snippet;

package/dist/components/Combobox.svelte

@@ -8,6 +8,12 @@
 		label: string;
 		/** A second line in `--muted`. */
 		description?: string;
+		/**
+		 * The heading the option sits under, as written; the default filter
+		 * matches it too. Options with the same group share one heading, in the
+		 * order each group first appears; options without one come first.
+		 */
+		group?: string;
 		disabled?: boolean;
 	};
 
@@ -51,7 +57,10 @@
 		 * The hint and the error stay under the field.
 		 */
 		labelBeside?: ComboboxLabelBeside;
-		/** Replaces the default filter: the label contains the text, ignoring case and accents. */
+		/**
+		 * Replaces the default filter: the label or the group contains the text,
+		 * ignoring case and accents.
+		 */
 		filter?: ComboboxFilter;
 		/** Shown in place of the options when nothing matches. */
 		emptyText?: string;
@@ -72,6 +81,7 @@
 	import { MediaQuery } from 'svelte/reactivity';
 	import { pop } from '../motion/index.js';
 	import { fadeIn } from './internal/fade-in.js';
+	import { groupOptions } from './internal/groups.js';
 	import Sheet from './internal/Sheet.svelte';
 
 	const uid = $props.id();
@@ -150,13 +160,19 @@
 	let query = $state('');
 
 	const fold = (s: string) => s.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLowerCase();
-	const byLabel: ComboboxFilter = (entry, q) => fold(entry.label).includes(fold(q));
+	const byLabelOrGroup: ComboboxFilter = (entry, q) => {
+		const needle = fold(q);
+		return fold(entry.label).includes(needle) || (!!entry.group && fold(entry.group).includes(needle));
+	};
 	const matches = $derived.by(() => {
 		const q = query.trim();
 		if (!q) return items;
-		const keep = filter ?? byLabel;
+		const keep = filter ?? byLabelOrGroup;
 		return items.filter((entry) => keep(entry, q));
 	});
+	// Options without a group, then each group that still has a match; a
+	// group whose options all filter out drops its heading too.
+	const grouped = $derived(groupOptions(matches));
 
 	// The highlight moved by keys gets the focus contour; a pointer's gets the
 	// hover tint alone. Focus itself stays in the input.
@@ -212,6 +228,11 @@
 		oninputProp?.(e);
 		query = e.currentTarget.value;
 		text = query;
+		// The matches show from the top, so Bits UI's highlight, which goes to
+		// the first option in view, lands on the first match, and no match
+		// waits above the fold or under a group heading.
+		const viewport = document.getElementById(listId)?.querySelector('[data-combobox-viewport]');
+		if (viewport) viewport.scrollTop = 0;
 	}
 
 	// A press on the field opens the list (openChanged selects its text).
@@ -271,12 +292,13 @@
 	// ContentStatic with forceMount reports placement once, at mount, while
 	// still closed. So Bits neither opens it at the chosen option nor scrolls
 	// to the option the keys move to; this does both, nearest edge first, as
-	// Bits does in the popover (Select does the same).
+	// Bits does in the popover (Select does the same). The viewport's
+	// scroll-padding keeps an option clear of a group heading stuck at the top.
 	function followHighlight(viewport: HTMLElement) {
 		const reveal = (option: Element | null) => {
 			if (!(option instanceof HTMLElement)) return;
-			const top = option.offsetTop;
-			const bottom = top + option.offsetHeight;
+			const top = option.offsetTop - (parseFloat(getComputedStyle(viewport).scrollPaddingTop) || 0);
+			const bottom = option.offsetTop + option.offsetHeight;
 			if (top < viewport.scrollTop) viewport.scrollTop = top;
 			else if (bottom > viewport.scrollTop + viewport.clientHeight) {
 				viewport.scrollTop = bottom - viewport.clientHeight;
@@ -484,35 +506,63 @@
 {#snippet options(inSheet: boolean)}
 	<BitsCombobox.Viewport>
 		{#snippet child({ props: viewportProps })}
-			<div {...viewportProps} class="hp-combobox-viewport" {@attach inSheet && followHighlight}>
-				{#each matches as entry (entry.value)}
-					<BitsCombobox.Item value={entry.value} label={entry.label} disabled={entry.disabled}>
-						{#snippet child({ props: optionProps, selected, highlighted })}
-							<div
-								{...optionProps}
-								class="hp-combobox-option"
-								data-described={entry.description ? '' : undefined}
-								aria-disabled={entry.disabled ? 'true' : undefined}
-							>
-								{#if itemContent}
-									{@render itemContent({ item: entry, selected, highlighted })}
-								{:else}
-									<span class="hp-combobox-option-label">{entry.label}</span>
-									{#if entry.description}
-										<span class="hp-combobox-option-description">{entry.description}</span>
-									{/if}
-								{/if}
+			<div
+				{...viewportProps}
+				class="hp-combobox-viewport"
+				data-grouped={grouped.groups.length ? '' : undefined}
+				{@attach inSheet && followHighlight}
+			>
+				{#each grouped.loose as entry (entry.value)}
+					{@render option(entry)}
+				{/each}
+				{#each grouped.groups as group (group.name)}
+					<!-- role="group", named by its heading, which is no option: keys
+					     skip it. -->
+					<BitsCombobox.Group>
+						{#snippet child({ props: groupProps })}
+							<div {...groupProps} class="hp-combobox-group">
+								<BitsCombobox.GroupHeading>
+									{#snippet child({ props: headingProps })}
+										<div {...headingProps} class="hp-combobox-group-heading">{group.name}</div>
+									{/snippet}
+								</BitsCombobox.GroupHeading>
+								{#each group.items as entry (entry.value)}
+									{@render option(entry)}
+								{/each}
 							</div>
 						{/snippet}
-					</BitsCombobox.Item>
+					</BitsCombobox.Group>
 				{/each}
 			</div>
 		{/snippet}
 	</BitsCombobox.Viewport>
 {/snippet}
 
-<!-- Outside the listbox, which may hold options only. Mounted while the
-	 list is open, so the text it gains when nothing matches is announced. -->
+{#snippet option(entry: ComboboxItem)}
+	<BitsCombobox.Item value={entry.value} label={entry.label} disabled={entry.disabled}>
+		{#snippet child({ props: optionProps, selected, highlighted })}
+			<div
+				{...optionProps}
+				class="hp-combobox-option"
+				data-described={entry.description ? '' : undefined}
+				aria-disabled={entry.disabled ? 'true' : undefined}
+			>
+				{#if itemContent}
+					{@render itemContent({ item: entry, selected, highlighted })}
+				{:else}
+					<span class="hp-combobox-option-label">{entry.label}</span>
+					{#if entry.description}
+						<span class="hp-combobox-option-description">{entry.description}</span>
+					{/if}
+				{/if}
+			</div>
+		{/snippet}
+	</BitsCombobox.Item>
+{/snippet}
+
+<!-- Outside the listbox, which may hold options and groups only. Mounted
+	 while the list is open, so the text it gains when nothing matches is
+	 announced. -->
 {#snippet empty(inSheet: boolean)}
 	<p class="hp-combobox-empty" data-form={inSheet ? 'sheet' : 'popover'} role="status">
 		{#if !matches.length}{emptyText}{/if}
@@ -746,6 +796,33 @@
 	.hp-combobox-list[data-empty] .hp-combobox-viewport[data-combobox-viewport] {
 		padding-block: 0;
 	}
+	/* An option the keys or the chosen value scroll to stays clear of the
+	   group heading stuck at the top: one heading line high. */
+	.hp-combobox-viewport[data-grouped] {
+		scroll-padding-top: calc(var(--space-2) + 16px + var(--space-1));
+	}
+
+	/* ---- Group headings: as Select's ------------------------------------ */
+
+	/* MenuGroup's heading: muted, on the options' text edge, 8px above and
+	   4px below. The text stays as written, because a group name may be the
+	   app's data (BRIEF, style rule 4). It stays at the top of the list while
+	   its options scroll under it, until the next group pushes it up; that is
+	   scrolling, not motion. It sticks to the viewport's edge, over its 4px
+	   padding, so nothing shows above it. */
+	.hp-combobox-group-heading {
+		position: sticky;
+		top: calc(-1 * var(--space-1));
+		z-index: 1;
+		padding: var(--space-2) var(--option-inset) var(--space-1);
+		background: var(--canvas);
+		color: var(--muted);
+		font-size: var(--type-label);
+		font-weight: 500;
+		line-height: 16px;
+		overflow-wrap: anywhere;
+		user-select: none;
+	}
 
 	/* ---- Options: Geist list items, sentence case ----------------------- */
 

package/dist/components/Combobox.svelte.d.ts

@@ -6,6 +6,12 @@ export type ComboboxItem = {
     label: string;
     /** A second line in `--muted`. */
     description?: string;
+    /**
+     * The heading the option sits under, as written; the default filter
+     * matches it too. Options with the same group share one heading, in the
+     * order each group first appears; options without one come first.
+     */
+    group?: string;
     disabled?: boolean;
 };
 export type ComboboxItemSnippetProps = {
@@ -45,7 +51,10 @@ export type ComboboxProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'id'>
      * The hint and the error stay under the field.
      */
     labelBeside?: ComboboxLabelBeside;
-    /** Replaces the default filter: the label contains the text, ignoring case and accents. */
+    /**
+     * Replaces the default filter: the label or the group contains the text,
+     * ignoring case and accents.
+     */
     filter?: ComboboxFilter;
     /** Shown in place of the options when nothing matches. */
     emptyText?: string;

package/dist/components/Dialog.svelte

@@ -309,13 +309,16 @@
 	/* ---- Body and actions, in every form -------------------------------- */
 
 	/* The top padding keeps a first field's focus contour (4px out, 2px
-	   wide) inside the scrolling box. */
+	   wide) inside the scrolling box. The scroll padding keeps a focused
+	   field's caret 8px clear of the action row when the browser reveals it,
+	   as when a TextArea grows while someone types. */
 	.hp-dialog-body {
 		display: grid;
 		align-content: start;
 		gap: var(--space-4);
 		min-width: 0;
 		padding: var(--space-2) var(--gutter);
+		scroll-padding-block: var(--space-2);
 		font-size: var(--type-body);
 		line-height: 24px;
 	}