@mystravil/hardpoint 0.0.0-stage → 0.1.0

package/dist/components/Tabs.svelte

@@ -0,0 +1,246 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import { Tabs as BitsTabs } from 'bits-ui';
+
+	export type TabsItem = {
+		/** Identifies the tab; the bound `value` holds the selected one. */
+		value: string;
+		/** The caps label. A short fixed string the app defines, never user data. */
+		label: string;
+		/** Shown in `--muted`; it cannot be selected and arrow keys skip it. */
+		disabled?: boolean;
+	};
+
+	/** Tabs may carry extra fields (a count, an icon name) that the `panel` snippet reads. */
+	export type TabsProps<T extends TabsItem = TabsItem> = Omit<
+		BitsTabs.RootProps,
+		'value' | 'orientation' | 'child' | 'children'
+	> & {
+		tabs: T[];
+		/** The selected tab's `value`. Bindable; defaults to the first tab that is not disabled. */
+		value?: string;
+		/** The tab list's accessible name, for example "Project sections". */
+		label: string;
+		/** Renders one tab's panel. Every panel stays mounted; the hidden ones carry `hidden`. */
+		panel: Snippet<[T]>;
+	};
+</script>
+
+<script lang="ts" generics="T extends TabsItem = TabsItem">
+	import { untrack } from 'svelte';
+	import { fadeIn } from './internal/fade-in.js';
+
+	let {
+		tabs,
+		value = $bindable(tabs.find((tab) => !tab.disabled)?.value ?? ''),
+		label,
+		panel,
+		class: className,
+		ref = $bindable(null),
+		onValueChange,
+		...rest
+	}: TabsProps<T> = $props();
+
+	let list: HTMLElement | null = $state(null);
+
+	// Shows the selected tab whole inside the list, with part of the next one
+	// (the list's scroll-padding). It scrolls the list alone, never the page
+	// (scrollIntoView would), and jumps: selection snaps (motion rule 3).
+	function reveal(list: HTMLElement, selected: string) {
+		const tab = Array.from(list.children).find(
+			(el): el is HTMLElement => el instanceof HTMLElement && el.dataset.value === selected
+		);
+		if (!tab) return;
+		const style = getComputedStyle(list);
+		// The tab's edges in the list's scroll coordinates, from rects: offsetLeft
+		// and offsetWidth round to whole pixels. The target rounds outward, so
+		// the padding never comes up a fraction short.
+		const listLeft = list.getBoundingClientRect().left + list.clientLeft;
+		const rect = tab.getBoundingClientRect();
+		const left = rect.left - listLeft + list.scrollLeft;
+		const start = Math.floor(left - (parseFloat(style.scrollPaddingLeft) || 0));
+		const end = Math.ceil(left + rect.width + (parseFloat(style.scrollPaddingRight) || 0));
+		if (start < list.scrollLeft) {
+			list.scrollTo({ left: start, behavior: 'instant' });
+		} else if (end > list.scrollLeft + list.clientWidth) {
+			list.scrollTo({ left: end - list.clientWidth, behavior: 'instant' });
+		}
+	}
+
+	// On the first render and whenever the selection changes.
+	$effect(() => {
+		if (list) reveal(list, value);
+	});
+
+	// Again whenever the list or a tab changes size: the web font arrives, the
+	// screen turns, or a hidden parent (another tab panel) shows the list. The
+	// watcher restarts whenever the set of tabs changes, not only their number,
+	// so a tab an app swaps in for another is watched too (each tab element is
+	// keyed by its value).
+	$effect(() => {
+		const el = list;
+		const values = tabs.map((tab) => tab.value);
+		if (!el || values.length === 0) return;
+		const observer = new ResizeObserver(() => reveal(el, value));
+		observer.observe(el);
+		for (const tab of el.children) observer.observe(tab);
+		return () => observer.disconnect();
+	});
+
+	// ---- Short motion: the panel (BRIEF, --dur-panel) ----------------------
+
+	// A panel chosen by a pointer or a touch fades in from 0 over
+	// --dur-panel. A panel chosen by a key (arrows, Home, End, Enter, Space)
+	// or by the app through `value` cuts, so holding an arrow key through the
+	// tabs never starts a fade (the frequency check). The input: the tab list
+	// keeps the last one it saw, from pointerdown and keydown in the capture
+	// phase, before Bits UI acts on them. Bits UI calls onValueChange only for
+	// a selection the user makes, never for a `value` the app sets, so the
+	// change notes there whether a pointer made it, and the effect below
+	// fades the new panel once it shows. A new selection cancels a fade that
+	// still runs. 0ms is a cut, as before the token.
+	let input: 'pointer' | 'key' | null = null;
+	let fadeTo: string | null = null;
+	let fade: Animation | null = null;
+
+	function changed(next: string) {
+		fadeTo = input === 'pointer' ? next : null;
+		onValueChange?.(next);
+	}
+
+	$effect(() => {
+		const selected = value;
+		untrack(() => {
+			fade?.cancel();
+			fade = null;
+			const chosen = fadeTo === selected;
+			fadeTo = null;
+			if (!chosen || !ref) return;
+			const shown = Array.from(ref.children).find(
+				(el): el is HTMLElement =>
+					el instanceof HTMLElement && el.classList.contains('hp-tabs-panel') && el.dataset.value === selected
+			);
+			if (shown) fade = fadeIn(shown, '--dur-panel');
+		});
+	});
+</script>
+
+<!--
+	Bits UI Tabs, rendered through `child` snippets so every element is this
+	component's markup and its styles stay scoped. Extra attributes, `class`
+	and Bits UI root props (`activationMode`, `loop`, `disabled`,
+	`onValueChange`) go to the root `div.hp-tabs`. Parts: `.hp-tabs-list`
+	(role tablist), `.hp-tabs-tab` (role tab, with Bits UI's `data-state` and
+	`data-value`), `.hp-tabs-panel` (role tabpanel).
+-->
+<BitsTabs.Root bind:value bind:ref onValueChange={changed} {...rest}>
+	{#snippet child({ props })}
+		<div {...props} class={['hp-tabs', className]}>
+			<BitsTabs.List bind:ref={list} aria-label={label}>
+				{#snippet child({ props })}
+					<div
+						{...props}
+						class="hp-tabs-list"
+						onpointerdowncapture={() => (input = 'pointer')}
+						onkeydowncapture={() => (input = 'key')}
+					>
+						{#each tabs as tab (tab.value)}
+							<BitsTabs.Trigger value={tab.value} disabled={tab.disabled}>
+								{#snippet child({ props })}
+									<button {...props} class="hp-tabs-tab hp-label hp-focus-inset">{tab.label}</button>
+								{/snippet}
+							</BitsTabs.Trigger>
+						{/each}
+					</div>
+				{/snippet}
+			</BitsTabs.List>
+			{#each tabs as tab (tab.value)}
+				<BitsTabs.Content value={tab.value}>
+					{#snippet child({ props })}
+						<div {...props} class="hp-tabs-panel">{@render panel(tab)}</div>
+					{/snippet}
+				</BitsTabs.Content>
+			{/each}
+		</div>
+	{/snippet}
+</BitsTabs.Root>
+
+<style>
+	/* In a flex or grid parent the tabs never grow wider than their column:
+	   the list scrolls instead of widening the page. */
+	.hp-tabs {
+		min-width: 0;
+	}
+
+	/* One row that scrolls sideways when the tabs do not fit. It reaches
+	   --bleed past the text edge, as the table band does, and each tab pads
+	   by --bleed, so the first label keeps the page's text edge. */
+	.hp-tabs-list {
+		display: flex;
+		margin-inline: calc(-1 * var(--bleed));
+		overflow-x: auto;
+		overscroll-behavior-x: contain;
+		/* Scrolling a tab into view leaves part of the next one showing. */
+		scroll-padding-inline: var(--space-8);
+		/* A thin bar on fine pointers, where a wheel cannot scroll sideways
+		   without one; touch swipes. */
+		scrollbar-width: thin;
+	}
+	@media (pointer: coarse) {
+		.hp-tabs-list {
+			scrollbar-width: none;
+		}
+	}
+
+	/* The visible box is the hit area: --control-height high (44px on
+	   coarse pointers) and never narrower than --hit-target. */
+	.hp-tabs-tab {
+		display: inline-flex;
+		flex: none;
+		align-items: center;
+		justify-content: center;
+		box-sizing: border-box;
+		min-width: var(--hit-target);
+		min-height: var(--control-height);
+		padding: 0 var(--bleed);
+		border: 0;
+		background: transparent;
+		color: var(--text);
+		white-space: nowrap;
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+	}
+
+	/* Selected: a 3px titanium edge on the side facing the panel and the
+	   selected tint, text unchanged. Selection snaps, so nothing on a tab
+	   transitions: a fading hover tint would also animate the tab an arrow
+	   key just left while the pointer rests on it. */
+	.hp-tabs-tab[data-state='active'] {
+		background: var(--surface-selected);
+		box-shadow: inset 0 -3px 0 var(--accent);
+	}
+
+	/* Hover: fine pointers only, never on the selected tab. */
+	@media (hover: hover) and (pointer: fine) {
+		.hp-tabs-tab[data-state='inactive']:hover:not(:disabled) {
+			background: var(--surface-hover);
+		}
+	}
+
+	/* Press: one step past hover, so it reads on a phone too. */
+	.hp-tabs-tab[data-state='inactive']:active:not(:disabled) {
+		background: var(--surface-raised);
+	}
+
+	.hp-tabs-tab:disabled {
+		color: var(--muted);
+		cursor: not-allowed;
+	}
+
+	/* A panel a pointer chose fades in over --dur-panel (see the script);
+	   otherwise it cuts. Margin, not padding, keeps the panel's focus
+	   contour clear of the tabs. */
+	.hp-tabs-panel {
+		margin-top: var(--space-6);
+	}
+</style>

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

@@ -0,0 +1,44 @@
+import type { Snippet } from 'svelte';
+import { Tabs as BitsTabs } from 'bits-ui';
+export type TabsItem = {
+    /** Identifies the tab; the bound `value` holds the selected one. */
+    value: string;
+    /** The caps label. A short fixed string the app defines, never user data. */
+    label: string;
+    /** Shown in `--muted`; it cannot be selected and arrow keys skip it. */
+    disabled?: boolean;
+};
+/** Tabs may carry extra fields (a count, an icon name) that the `panel` snippet reads. */
+export type TabsProps<T extends TabsItem = TabsItem> = Omit<BitsTabs.RootProps, 'value' | 'orientation' | 'child' | 'children'> & {
+    tabs: T[];
+    /** The selected tab's `value`. Bindable; defaults to the first tab that is not disabled. */
+    value?: string;
+    /** The tab list's accessible name, for example "Project sections". */
+    label: string;
+    /** Renders one tab's panel. Every panel stays mounted; the hidden ones carry `hidden`. */
+    panel: Snippet<[T]>;
+};
+declare function $$render<T extends TabsItem = TabsItem>(): {
+    props: TabsProps<T>;
+    exports: {};
+    bindings: "value" | "ref";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends TabsItem = TabsItem> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "value" | "ref";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends TabsItem = TabsItem>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends TabsItem = TabsItem>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Tabs: $$IsomorphicComponent;
+type Tabs<T extends TabsItem = TabsItem> = InstanceType<typeof Tabs<T>>;
+export default Tabs;

package/dist/components/Tag.svelte

@@ -0,0 +1,40 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	/** The elements a tag renders as. Headings for a tag that names a section. */
+	export type TagElement = 'p' | 'span' | 'div' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+	export type TagProps = HTMLAttributes<HTMLElement> & {
+		/**
+		 * The element to render: `p` (default), or a heading when the tag names
+		 * a section, with an `id` the section's `aria-labelledby` points at.
+		 */
+		as?: TagElement;
+		children?: Snippet;
+	};
+</script>
+
+<script lang="ts">
+	let { as = 'p', class: className, children, ...rest }: TagProps = $props();
+</script>
+
+<!--
+	A small solid titanium block with black caps (BRIEF, visual rule 2). A tag
+	may sit above a block to name it (da3-51); it sets no outer margin, so the
+	layout spaces it.
+-->
+<svelte:element this={as} {...rest} class={['hp-tag', 'hp-label', className]}>{@render children?.()}</svelte:element>
+
+<style>
+	/* The caps type comes from .hp-label. The block never stretches to its
+	   container, in block, grid and flex layouts alike. */
+	.hp-tag {
+		justify-self: start;
+		width: fit-content;
+		/* matches the approved specimen */
+		padding: 2px 6px;
+		background: var(--accent);
+		color: var(--canvas);
+	}
+</style>

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

@@ -0,0 +1,15 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/** The elements a tag renders as. Headings for a tag that names a section. */
+export type TagElement = 'p' | 'span' | 'div' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+export type TagProps = HTMLAttributes<HTMLElement> & {
+    /**
+     * The element to render: `p` (default), or a heading when the tag names
+     * a section, with an `id` the section's `aria-labelledby` points at.
+     */
+    as?: TagElement;
+    children?: Snippet;
+};
+declare const Tag: import("svelte").Component<TagProps, {}, "">;
+type Tag = ReturnType<typeof Tag>;
+export default Tag;

package/dist/components/TextField.svelte

@@ -0,0 +1,256 @@
+<script lang="ts" module>
+	import type { HTMLInputAttributes } from 'svelte/elements';
+
+	/** The text input types the well suits. For numbers use `text` with `inputmode="numeric"`. */
+	export type TextFieldType = 'text' | 'email' | 'password' | 'search' | 'tel' | 'url';
+
+	/** From which width the label sits beside the well: 600px, 900px or 1200px. */
+	export type TextFieldBreakpoint = 'medium' | 'expanded' | 'large';
+
+	/** Attributes and handlers not listed here go to the `<input>`. */
+	export type TextFieldProps = Omit<HTMLInputAttributes, 'type' | 'value' | 'children'> & {
+		/** The caps field label above the well. Required: a placeholder is never the only label. */
+		label: string;
+		/** The text. Bindable. */
+		value?: string;
+		type?: TextFieldType;
+		/** Guidance under the well in `--muted`, linked by `aria-describedby`. */
+		hint?: string;
+		/**
+		 * The error to show under the well, with an icon, linked by
+		 * `aria-describedby`; it sets `aria-invalid`. Say how to fix the
+		 * problem. The app validates; the field shows what it is given.
+		 */
+		error?: string;
+		/**
+		 * The label sits above the well by default. `true` puts it beside the
+		 * well at every width; a breakpoint puts it beside from that width up.
+		 * The hint and the error stay under the well.
+		 */
+		labelBeside?: boolean | TextFieldBreakpoint;
+		/** The `<input>`, for example to focus the first error on submit. */
+		ref?: HTMLInputElement | null;
+	};
+</script>
+
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import { Label } from 'bits-ui';
+	import { fadeIn } from './internal/fade-in.js';
+
+	const uid = $props.id();
+
+	let {
+		label,
+		value = $bindable(''),
+		type = 'text',
+		hint,
+		error,
+		labelBeside = false,
+		id = uid,
+		disabled,
+		ref = $bindable(null),
+		class: className,
+		'aria-describedby': describedBy,
+		'aria-invalid': ariaInvalid,
+		...rest
+	}: TextFieldProps = $props();
+
+	const hintId = $derived(`${id}-hint`);
+	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) --------------------
+
+	// An error that appears after the first render fades in from 0 over
+	// --dur-message, and the well's edge fades to --danger with it (the CSS
+	// below). An error that clears goes at once, and so does the red edge. A
+	// field that renders or mounts with an error, such as one in a dialog
+	// that opens, shows it at once. 0ms is a snap.
+	let root: HTMLDivElement | null = $state(null);
+	let errorShown = untrack(() => !!error);
+	$effect(() => {
+		const shown = !!error;
+		untrack(() => {
+			const appeared = shown && !errorShown;
+			errorShown = shown;
+			const message = appeared ? root?.querySelector(':scope > .error') : null;
+			if (message) fadeIn(message, '--dur-message');
+		});
+	});
+</script>
+
+<!--
+	A single-line text input in the black well, with a plain caps label above
+	it (Bits UI Label), an optional hint and an inline error below. Extra
+	attributes (`name`, `inputmode`, `autocomplete`, `enterkeyhint`,
+	`required`), handlers and `class` go to the <input>.
+-->
+<div
+	bind:this={root}
+	class="hp-text-field"
+	data-invalid={error ? '' : undefined}
+	data-disabled={disabled ? '' : undefined}
+	data-label-beside={labelBeside === true ? 'always' : labelBeside || undefined}
+>
+	<Label.Root for={id}>
+		{#snippet child({ props })}
+			<label {...props} class="hp-label">{label}</label>
+		{/snippet}
+	</Label.Root>
+	<input
+		{...rest}
+		bind:this={ref}
+		bind:value
+		{id}
+		{type}
+		{disabled}
+		class={['hp-well', className]}
+		aria-describedby={describedByIds}
+		aria-invalid={error ? true : ariaInvalid}
+	/>
+	{#if hint}
+		<p class="hint hp-caption" id={hintId}>{hint}</p>
+	{/if}
+	{#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>
+
+<style>
+	.hp-text-field {
+		display: grid;
+		gap: var(--space-1);
+		min-width: 0;
+	}
+	label {
+		color: var(--muted);
+	}
+	input {
+		display: block;
+		width: 100%;
+		min-width: 0;
+	}
+	input::placeholder {
+		color: var(--muted);
+		opacity: 1;
+	}
+
+	/* Invalid: the boundary turns --danger (5.9:1 on black), never alone:
+	   the icon and the message say what is wrong. Keyed on the root's
+	   data-invalid, set by `error`, so an aria-invalid the app passes
+	   without a message draws no red border. The edge fades to --danger
+	   over --dur-message with the message; the transition belongs to this
+	   rule, so the edge goes back at once when the error clears. The hover
+	   fill keeps base.css's timing. */
+	[data-invalid] input {
+		border-color: var(--danger);
+		transition:
+			background-color var(--dur-hover) var(--settle),
+			border-color var(--dur-message) var(--settle);
+	}
+	[data-invalid] input:disabled {
+		border-color: var(--border);
+	}
+
+	.hint {
+		margin: 0;
+		color: var(--muted);
+	}
+	.error {
+		display: flex;
+		gap: var(--space-2);
+		margin: 0;
+		color: var(--danger);
+	}
+	/* The first message starts 8px under the well, clear of the focus
+	   contour (2px, drawn 4px outside the well). */
+	input + .hint,
+	input + .error {
+		margin-top: var(--space-1);
+	}
+	/* 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;
+	}
+
+	/* Beside the well, the label keeps its one line in the first column; the
+	   well, hint and error share the second. */
+	[data-label-beside='always'] {
+		grid-template-columns: auto minmax(0, 1fr);
+		column-gap: var(--space-2);
+	}
+	[data-label-beside='always'] label {
+		grid-row: 1;
+		align-self: center;
+		white-space: nowrap;
+	}
+	[data-label-beside='always'] input,
+	[data-label-beside='always'] p {
+		grid-column: 2;
+	}
+	@media (min-width: 600px) {
+		[data-label-beside='medium'] {
+			grid-template-columns: auto minmax(0, 1fr);
+			column-gap: var(--space-2);
+		}
+		[data-label-beside='medium'] label {
+			grid-row: 1;
+			align-self: center;
+			white-space: nowrap;
+		}
+		[data-label-beside='medium'] input,
+		[data-label-beside='medium'] p {
+			grid-column: 2;
+		}
+	}
+	@media (min-width: 900px) {
+		[data-label-beside='expanded'] {
+			grid-template-columns: auto minmax(0, 1fr);
+			column-gap: var(--space-2);
+		}
+		[data-label-beside='expanded'] label {
+			grid-row: 1;
+			align-self: center;
+			white-space: nowrap;
+		}
+		[data-label-beside='expanded'] input,
+		[data-label-beside='expanded'] p {
+			grid-column: 2;
+		}
+	}
+	@media (min-width: 1200px) {
+		[data-label-beside='large'] {
+			grid-template-columns: auto minmax(0, 1fr);
+			column-gap: var(--space-2);
+		}
+		[data-label-beside='large'] label {
+			grid-row: 1;
+			align-self: center;
+			white-space: nowrap;
+		}
+		[data-label-beside='large'] input,
+		[data-label-beside='large'] p {
+			grid-column: 2;
+		}
+	}
+</style>

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

@@ -0,0 +1,32 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+/** The text input types the well suits. For numbers use `text` with `inputmode="numeric"`. */
+export type TextFieldType = 'text' | 'email' | 'password' | 'search' | 'tel' | 'url';
+/** From which width the label sits beside the well: 600px, 900px or 1200px. */
+export type TextFieldBreakpoint = 'medium' | 'expanded' | 'large';
+/** Attributes and handlers not listed here go to the `<input>`. */
+export type TextFieldProps = Omit<HTMLInputAttributes, 'type' | 'value' | 'children'> & {
+    /** The caps field label above the well. Required: a placeholder is never the only label. */
+    label: string;
+    /** The text. Bindable. */
+    value?: string;
+    type?: TextFieldType;
+    /** Guidance under the well in `--muted`, linked by `aria-describedby`. */
+    hint?: string;
+    /**
+     * The error to show under the well, with an icon, linked by
+     * `aria-describedby`; it sets `aria-invalid`. Say how to fix the
+     * problem. The app validates; the field shows what it is given.
+     */
+    error?: string;
+    /**
+     * The label sits above the well by default. `true` puts it beside the
+     * well at every width; a breakpoint puts it beside from that width up.
+     * The hint and the error stay under the well.
+     */
+    labelBeside?: boolean | TextFieldBreakpoint;
+    /** The `<input>`, for example to focus the first error on submit. */
+    ref?: HTMLInputElement | null;
+};
+declare const TextField: import("svelte").Component<TextFieldProps, {}, "value" | "ref">;
+type TextField = ReturnType<typeof TextField>;
+export default TextField;