@mystravil/hardpoint 0.0.0-stage → 0.2.0

package/dist/components/TooltipGroup.svelte

@@ -0,0 +1,46 @@
+<script lang="ts" module>
+	import { createContext, type Snippet } from 'svelte';
+
+	/**
+	 * Wraps a row of controls whose tooltips belong together, such as a
+	 * toolbar. The group renders no element of its own: it sets up one Bits UI
+	 * `Tooltip.Provider` that every `Tooltip` inside it shares, so once one
+	 * tooltip in the row has opened, the next opens at once while the pointer
+	 * moves along the row. Lay out the controls with your own markup inside it.
+	 */
+	export type TooltipGroupProps = {
+		/** The controls and their tooltips. */
+		children: Snippet;
+		/**
+		 * Milliseconds a pointer rests on a control before the first tooltip
+		 * opens (default 700, Bits UI's, as for a Tooltip outside a group). A
+		 * Tooltip's own `delayDuration` wins over it.
+		 */
+		delayDuration?: number;
+		/**
+		 * Milliseconds after a tooltip in the group closes during which the next
+		 * one opens without the delay (default 300, Bits UI's). 0 makes every
+		 * tooltip wait the full delay.
+		 */
+		skipDelayDuration?: number;
+	};
+
+	const [, setGroup, hasGroup] = createContext<true>();
+
+	/** A Tooltip inside a group uses the group's provider instead of its own. */
+	export function inTooltipGroup(): boolean {
+		return hasGroup();
+	}
+</script>
+
+<script lang="ts">
+	import { Tooltip } from 'bits-ui';
+
+	let { children, delayDuration, skipDelayDuration }: TooltipGroupProps = $props();
+
+	setGroup(true);
+</script>
+
+<Tooltip.Provider {delayDuration} {skipDelayDuration}>
+	{@render children()}
+</Tooltip.Provider>

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

@@ -0,0 +1,29 @@
+import { type Snippet } from 'svelte';
+/**
+ * Wraps a row of controls whose tooltips belong together, such as a
+ * toolbar. The group renders no element of its own: it sets up one Bits UI
+ * `Tooltip.Provider` that every `Tooltip` inside it shares, so once one
+ * tooltip in the row has opened, the next opens at once while the pointer
+ * moves along the row. Lay out the controls with your own markup inside it.
+ */
+export type TooltipGroupProps = {
+    /** The controls and their tooltips. */
+    children: Snippet;
+    /**
+     * Milliseconds a pointer rests on a control before the first tooltip
+     * opens (default 700, Bits UI's, as for a Tooltip outside a group). A
+     * Tooltip's own `delayDuration` wins over it.
+     */
+    delayDuration?: number;
+    /**
+     * Milliseconds after a tooltip in the group closes during which the next
+     * one opens without the delay (default 300, Bits UI's). 0 makes every
+     * tooltip wait the full delay.
+     */
+    skipDelayDuration?: number;
+};
+/** A Tooltip inside a group uses the group's provider instead of its own. */
+export declare function inTooltipGroup(): boolean;
+declare const TooltipGroup: import("svelte").Component<TooltipGroupProps, {}, "">;
+type TooltipGroup = ReturnType<typeof TooltipGroup>;
+export default TooltipGroup;

package/dist/components/internal/Scrim.svelte

@@ -0,0 +1,52 @@
+<script lang="ts" module>
+	/**
+	 * The z-index token an overlay sits on (tokens.css, layer scale).
+	 * `dialog`: dialogs, their sheets and the shell drawer. `popover`:
+	 * popovers, menus, select lists and comboboxes, and their sheets on
+	 * compact widths, so they open over a dialog.
+	 */
+	export type OverlayLayer = 'dialog' | 'popover';
+
+	export type ScrimProps = {
+		/** Shown while true. Pass the Bits UI content's `open`. */
+		open: boolean;
+		layer: OverlayLayer;
+	};
+</script>
+
+<script lang="ts">
+	import { fade } from '../../motion/index.js';
+
+	let { open, layer }: ScrimProps = $props();
+
+	// A press on the scrim keeps focus where it is (on the trigger, or
+	// inside a dialog). The press still reaches Bits UI as an outside
+	// interaction, which closes the overlay.
+	function keepFocus(e: PointerEvent) {
+		e.preventDefault();
+	}
+</script>
+
+<!--
+	Dims the page behind a dialog or sheet. Render it just before the panel,
+	on the same layer, so the panel paints over it. It fades with the panel's
+	timing (--dur-sheet in, --dur-sheet-exit out).
+-->
+{#if open}
+	<div class="hp-scrim" data-layer={layer} aria-hidden="true" onpointerdown={keepFocus} transition:fade></div>
+{/if}
+
+<style>
+	/* While a floating list is open Bits UI sets pointer-events: none on
+	   <body>; the scrim takes presses again, so a tap on it closes. */
+	.hp-scrim {
+		position: fixed;
+		inset: 0;
+		z-index: var(--layer-dialog);
+		background: var(--scrim);
+		pointer-events: auto;
+	}
+	.hp-scrim[data-layer='popover'] {
+		z-index: var(--layer-popover);
+	}
+</style>

package/dist/components/internal/Scrim.svelte.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The z-index token an overlay sits on (tokens.css, layer scale).
+ * `dialog`: dialogs, their sheets and the shell drawer. `popover`:
+ * popovers, menus, select lists and comboboxes, and their sheets on
+ * compact widths, so they open over a dialog.
+ */
+export type OverlayLayer = 'dialog' | 'popover';
+export type ScrimProps = {
+    /** Shown while true. Pass the Bits UI content's `open`. */
+    open: boolean;
+    layer: OverlayLayer;
+};
+declare const Scrim: import("svelte").Component<ScrimProps, {}, "">;
+type Scrim = ReturnType<typeof Scrim>;
+export default Scrim;

package/dist/components/internal/Sheet.svelte

@@ -0,0 +1,263 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import type { OverlayLayer } from './Scrim.svelte';
+
+	/** Attributes and handlers not listed here go to the panel. */
+	export type SheetProps = Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> & {
+		/**
+		 * Shown while true. Pass the `open` that the Bits UI content's
+		 * `child` snippet receives (render the content with `forceMount`), so
+		 * the sheet and its scrim slide and fade out before they unmount.
+		 */
+		open: boolean;
+		/** The title row's text, in tracked caps. */
+		title: string;
+		/** The title element's `id`, so the content can be labelled by it. */
+		titleId?: string;
+		/** The title element: `p`, or `h2` when the sheet is a dialog. */
+		titleTag?: 'p' | 'h2';
+		/** The z-index token: `dialog` for dialogs, `popover` for everything else. */
+		layer: OverlayLayer;
+		/**
+		 * Called by the close button and by a swipe down. A tap on the scrim
+		 * and Escape close through Bits UI.
+		 */
+		onclose: () => void;
+		/** The close button's accessible name. */
+		closeLabel?: string;
+		/** The panel element. */
+		ref?: HTMLElement | null;
+		/** The body, under the title row. It scrolls if it does not fit. */
+		children: Snippet;
+		/** A row pinned under the body, such as a dialog's actions. */
+		footer?: Snippet;
+	};
+</script>
+
+<script lang="ts">
+	import { sheet } from '../../motion/index.js';
+	import Scrim from './Scrim.svelte';
+	import { swipeDismiss } from './swipe-dismiss.js';
+	import { followVisualViewport } from './visual-viewport.svelte.js';
+
+	let {
+		open,
+		title,
+		titleId,
+		titleTag = 'p',
+		layer,
+		onclose,
+		closeLabel = 'Close',
+		ref = $bindable(null),
+		children,
+		footer,
+		class: className,
+		...rest
+	}: SheetProps = $props();
+
+	let body = $state<HTMLElement | null>(null);
+
+	// The sheet follows the visual viewport while it is open (decided
+	// 2026-11-10; internal/visual-viewport.svelte.ts): while the on-screen
+	// keyboard shortens it, the sheet's bottom edge sits on its bottom edge
+	// and the sheet may grow to its height less the header row's
+	// (--header-height and the top safe area), where it was half the screen.
+	// The focused field in the body stays in sight.
+	const viewport = followVisualViewport(() => open, () => body);
+
+	// The press that opened the sheet never acts on what the sheet now shows
+	// under the finger (decided 2026-11-10). On touch, Bits UI's Menu and
+	// Select triggers open on pointerup, and the click that follows lands on
+	// the sheet, which under reduced motion fades in where it ends up; a
+	// mouse opens them on pointerdown, and its pointerup on an item counts
+	// as a choice. So until a press starts inside the sheet, a pointerup or a
+	// pointer's click inside it stops here. A click from Enter, Space or
+	// element.click() has detail 0 and always passes.
+	function ignoreOpeningPress(node: HTMLElement) {
+		let pressed = false;
+		const press = () => (pressed = true);
+		const guard = (e: MouseEvent) => {
+			if (pressed || (e.type === 'click' && e.detail === 0)) return;
+			e.preventDefault();
+			e.stopImmediatePropagation();
+		};
+		const capture = { capture: true };
+		node.addEventListener('pointerdown', press, capture);
+		node.addEventListener('pointerup', guard, capture);
+		node.addEventListener('click', guard, capture);
+		return () => {
+			node.removeEventListener('pointerdown', press, capture);
+			node.removeEventListener('pointerup', guard, capture);
+			node.removeEventListener('click', guard, capture);
+		};
+	}
+</script>
+
+<!--
+	The bottom sheet every overlay uses on compact widths (BRIEF, Apps and
+	phones: Overlays): a scrim, then a panel at the bottom edge with a handle,
+	a caps title, a close button, the body and an optional footer. It opens at
+	half the screen at most, with no drag to expand; the body scrolls inside.
+	A swipe down dismisses it (internal/swipe-dismiss.ts). While the visual
+	viewport is shorter than the layout viewport (the on-screen keyboard), it
+	sits on top of it and may fill the space above it. The press that opened
+	it does not act inside it.
+
+	Render it inside the Bits UI content's `child` snippet and spread the
+	snippet's `props` onto it when the panel is the content element (a
+	dialog), or onto an element in the body when the content is a list (a
+	menu, a select): then pass `onInteractOutside` to the content and call
+	`preventDefault()` for presses inside `ref`, so the title row does not
+	count as outside.
+-->
+<Scrim {open} {layer} />
+{#if open}
+	{@const lifted = viewport.current}
+	<div
+		bind:this={ref}
+		{...rest}
+		class={['hp-sheet', className]}
+		data-layer={layer}
+		style:bottom={lifted ? `calc(100% - ${lifted.bottom}px)` : undefined}
+		style:padding-bottom={lifted ? '0px' : undefined}
+		style:--sheet-max-height={lifted
+			? `calc(${lifted.height}px - var(--header-height) - env(safe-area-inset-top))`
+			: undefined}
+		transition:sheet
+		{@attach ignoreOpeningPress}
+		{@attach swipeDismiss(() => onclose())}
+	>
+		<div class="hp-sheet-head">
+			<span class="hp-sheet-handle" aria-hidden="true"></span>
+			<svelte:element this={titleTag} id={titleId} class="hp-sheet-title">{title}</svelte:element>
+			<button type="button" class="hp-sheet-close" aria-label={closeLabel} onclick={() => onclose()}>
+				<svg
+					viewBox="0 0 16 16"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="1.5"
+					stroke-linecap="square"
+					aria-hidden="true"
+				>
+					<path d="M3 3l10 10M13 3L3 13" />
+				</svg>
+			</button>
+		</div>
+		<div class="hp-sheet-body" bind:this={body}>
+			{@render children()}
+		</div>
+		{#if footer}
+			<div class="hp-sheet-footer">
+				{@render footer()}
+			</div>
+		{/if}
+	</div>
+{/if}
+
+<style>
+	/* While a floating list is open Bits UI sets pointer-events: none on
+	   <body>; the panel takes presses again. */
+	.hp-sheet {
+		/* The height cap: half the screen, or the room above the on-screen
+		   keyboard while it is up (set inline). A list that must keep its
+		   height while it filters asks for this. */
+		--sheet-max-height: 50dvh;
+
+		position: fixed;
+		inset: auto 0 0;
+		z-index: var(--layer-dialog);
+		display: flex;
+		flex-direction: column;
+		box-sizing: border-box;
+		/* Opens at half the screen at most; the body scrolls inside. */
+		max-height: var(--sheet-max-height);
+		padding: 0 env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left);
+		border-top: 1px solid var(--border-control);
+		background: var(--canvas);
+		color: var(--text);
+		overscroll-behavior: contain;
+		pointer-events: auto;
+	}
+	.hp-sheet[data-layer='popover'] {
+		z-index: var(--layer-popover);
+	}
+
+	/* The grab area: handle, title and close button. The swipe owns touches
+	   here; the body below keeps its scroll until it reaches the top. */
+	.hp-sheet-head {
+		flex: none;
+		display: grid;
+		grid-template-columns: minmax(0, 1fr) auto;
+		align-items: start;
+		padding: 0 var(--space-1) 0 var(--gutter);
+		touch-action: none;
+	}
+	.hp-sheet-handle {
+		grid-column: 1 / -1;
+		justify-self: center;
+		width: var(--space-8);
+		height: var(--space-1);
+		margin-top: var(--space-2);
+		background: var(--border-control);
+	}
+	/* Tracked caps at the compact view-title size. A long title wraps (200
+	   percent zoom); the padding centres its first line on the 44px close
+	   button, so a single line sits where it always did. The clip stays: it
+	   keeps the first glyph's antialiasing inside the text edge, as before. */
+	.hp-sheet-title {
+		overflow: hidden;
+		padding-block: calc((44px - 1lh) / 2);
+		font-size: var(--type-body);
+		font-weight: 500;
+		line-height: 24px;
+		letter-spacing: var(--label-tracking);
+		text-transform: var(--label-transform);
+		overflow-wrap: anywhere;
+	}
+	.hp-sheet-close {
+		display: grid;
+		place-items: center;
+		width: 44px;
+		height: 44px;
+		padding: 0;
+		border: 0;
+		background: transparent;
+		color: var(--text);
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+	}
+	.hp-sheet-close svg {
+		width: var(--space-4);
+		height: var(--space-4);
+	}
+	.hp-sheet-close:active {
+		background: var(--surface-raised);
+	}
+	@media (hover: hover) and (pointer: fine) {
+		.hp-sheet-close {
+			transition: background-color var(--dur-hover) var(--settle);
+		}
+		.hp-sheet-close:hover {
+			background: var(--surface-hover);
+		}
+		.hp-sheet-close:active {
+			background: var(--surface-raised);
+			transition-duration: var(--dur-press);
+		}
+	}
+
+	/* A flex column, so a list inside can take the rest of the height
+	   (flex: 1 1 auto; min-height: 0) and scroll on its own. */
+	.hp-sheet-body {
+		display: flex;
+		flex-direction: column;
+		flex: 1 1 auto;
+		min-height: 0;
+		overflow-y: auto;
+		overscroll-behavior: contain;
+	}
+	.hp-sheet-footer {
+		flex: none;
+	}
+</style>

package/dist/components/internal/Sheet.svelte.d.ts

@@ -0,0 +1,36 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { OverlayLayer } from './Scrim.svelte';
+/** Attributes and handlers not listed here go to the panel. */
+export type SheetProps = Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> & {
+    /**
+     * Shown while true. Pass the `open` that the Bits UI content's
+     * `child` snippet receives (render the content with `forceMount`), so
+     * the sheet and its scrim slide and fade out before they unmount.
+     */
+    open: boolean;
+    /** The title row's text, in tracked caps. */
+    title: string;
+    /** The title element's `id`, so the content can be labelled by it. */
+    titleId?: string;
+    /** The title element: `p`, or `h2` when the sheet is a dialog. */
+    titleTag?: 'p' | 'h2';
+    /** The z-index token: `dialog` for dialogs, `popover` for everything else. */
+    layer: OverlayLayer;
+    /**
+     * Called by the close button and by a swipe down. A tap on the scrim
+     * and Escape close through Bits UI.
+     */
+    onclose: () => void;
+    /** The close button's accessible name. */
+    closeLabel?: string;
+    /** The panel element. */
+    ref?: HTMLElement | null;
+    /** The body, under the title row. It scrolls if it does not fit. */
+    children: Snippet;
+    /** A row pinned under the body, such as a dialog's actions. */
+    footer?: Snippet;
+};
+declare const Sheet: import("svelte").Component<SheetProps, {}, "ref">;
+type Sheet = ReturnType<typeof Sheet>;
+export default Sheet;

package/dist/components/internal/fade-in.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Short motion (BRIEF): fades `node` in from opacity 0 over the duration
+ * token `token`, such as `--dur-panel`, on `--settle`. Both are read from the
+ * node now, so a retuned token applies. At 0ms it does nothing and the node
+ * shows at once, as it did before the token existed. Opacity only, so it
+ * runs under reduced motion too. Call it after the change is in the DOM and
+ * before the next frame, so the first frame already shows opacity 0. Returns
+ * the fade, or null when there is none.
+ */
+export declare function fadeIn(node: Element, token: string): Animation | null;

package/dist/components/internal/fade-in.js

@@ -0,0 +1,20 @@
+import { duration } from '../../motion/transitions.js';
+/**
+ * Short motion (BRIEF): fades `node` in from opacity 0 over the duration
+ * token `token`, such as `--dur-panel`, on `--settle`. Both are read from the
+ * node now, so a retuned token applies. At 0ms it does nothing and the node
+ * shows at once, as it did before the token existed. Opacity only, so it
+ * runs under reduced motion too. Call it after the change is in the DOM and
+ * before the next frame, so the first frame already shows opacity 0. Returns
+ * the fade, or null when there is none.
+ */
+export function fadeIn(node, token) {
+    const ms = duration(node, token);
+    if (ms <= 0)
+        return null;
+    const settle = getComputedStyle(node).getPropertyValue('--settle').trim();
+    return node.animate([{ opacity: 0 }, { opacity: 1 }], {
+        duration: ms,
+        easing: CSS.supports('transition-timing-function', settle) ? settle : 'ease-out'
+    });
+}

package/dist/components/internal/groups.d.ts

@@ -0,0 +1,14 @@
+export type OptionGroup<T> = {
+    name: string;
+    items: T[];
+};
+export type GroupedOptions<T> = {
+    /** The items without a group, in their order. */
+    loose: T[];
+    groups: OptionGroup<T>[];
+    /** Every item in the order the list shows them. */
+    ordered: T[];
+};
+export declare function groupOptions<T extends {
+    group?: string;
+}>(items: readonly T[]): GroupedOptions<T>;

package/dist/components/internal/groups.js

@@ -0,0 +1,23 @@
+// Options in named groups, in one list (Select, Combobox, NativeSelect).
+// Items without a group come first, before any heading; then each group,
+// in the order its first item appears. Items keep their order inside a
+// group. An empty `group` counts as none, because a heading needs text.
+export function groupOptions(items) {
+    const loose = [];
+    const byName = new Map();
+    for (const item of items) {
+        if (!item.group) {
+            loose.push(item);
+            continue;
+        }
+        const members = byName.get(item.group);
+        if (members)
+            members.push(item);
+        else
+            byName.set(item.group, [item]);
+    }
+    if (!byName.size)
+        return { loose, groups: [], ordered: loose };
+    const groups = Array.from(byName, ([name, members]) => ({ name, items: members }));
+    return { loose, groups, ordered: loose.concat(...groups.map((g) => g.items)) };
+}

package/dist/components/internal/resolve.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shows `image` on `canvas` as a mosaic that sharpens one step per `step`
+ * ms, then calls `done`. The canvas carries `data-step` (1 to 5) and
+ * `data-block` (the block size in device pixels) for the step on screen.
+ * When the box is empty or the image has no size, `done` runs at once.
+ * Returns a stop function.
+ */
+export declare function resolveImage(canvas: HTMLCanvasElement, image: HTMLImageElement, step: number, done: () => void): () => void;