@vit-foundation/ui 0.30.0 → 0.32.0

package/README.md

@@ -34,6 +34,7 @@ Everything exports flat from the root, and again grouped by role:
 | [`/community`](./docs/components/community.md)                  | AuthPageShell, LoginForm, SignupForm, GoogleAuthForm, AccountPanel, NewsletterSignup, CommentSection, ReactionBar, ContactForm                                                                                                                                                    |
 | [`/admin`](./docs/components/admin.md)                          | DecorMosaic, PageHeading, Sidebar — shell-level composition for the foundation's internal tools                                                                                                                                                                                   |
 | [`/scrolly`](./docs/components/scrolly.md)                      | ScrollySteps, ScrollyStepIndicator, CrossfadeVideo, GlassCard, the stepStyle ramp — the only entry point that does NOT re-export from the root, and the only one with a peer of its own                                                                                           |
+| [`/madlib`](./docs/components/madlib.md)                        | Madlib, InlineSelect, the sentence-tree helpers (walkTree, completePath, defaultPath, replaceAt, leafPaths) — a sentence with blanks, themed with `--vit-madlib-*`; like `/scrolly`, not re-exported from the root                                                                |
 | [`/edit`](./docs/edit-mode.md)                                  | Editable, setEditAdapter(adapter, EDIT_CHROME)/getEditAdapter, descriptors and helpers, collectionEditing, LocalizedText                                                                                                                                                          |
 | [`/config`](./docs/getting-started.md#wiring-an-app-uiprovider) | UiProvider, UiConfig, the locale set, the default Catalan messages                                                                                                                                                                                                                |
 | `/contract`                                                     | The component-free half: LOCALES, BASE_LOCALE, localize, REACTIONS, PAGE_COPY_KEYS and the edit-descriptor types — the one subpath a host may import from SERVER code                                                                                                             |

package/dist/components/madlib/InlineSelect.svelte

@@ -0,0 +1,221 @@
+<!--
+  @component InlineSelect
+
+  A select that sits inside running text: the chosen label, underlined, with a
+  small caret, and a listbox that drops below it. It inherits the font, size
+  and line-height of the text around it, which is the whole point — a native
+  `<select>` cannot be made to read as a word in a sentence.
+
+  It is the control `<Madlib>` renders for each blank, and it is exported on
+  its own for a lone blank in a heading ("Practices in [Spain]").
+
+  ## Theming
+  Reads the madlib token family, with fallbacks, so it renders standalone:
+
+  | property                       | role                                   |
+  |--------------------------------|----------------------------------------|
+  | `--vit-madlib-control-weight`  | weight of the chosen label             |
+  | `--vit-madlib-muted-color`     | the unchosen options                   |
+  | `--vit-madlib-select-accent`   | the underline while open or hovered    |
+  | `--vit-madlib-menu-bg`         | the listbox surface                    |
+  | `--vit-madlib-menu-hover`      | the option under the pointer / chosen  |
+  | `--vit-madlib-menu-shadow`     | the listbox shadow                     |
+  | `--vit-madlib-menu-max-height` | the listbox scroll height              |
+  | `--vit-madlib-menu-z`          | the listbox stacking order             |
+
+  @property value - The chosen option's value
+  @property options - The options offered, in order
+  @property onchange - Fired with the new value when an option is picked
+  @property onopen - Fired when the listbox is opened, before it shows
+  @property label - Accessible name for the control, when the surrounding text does not give one
+  @property class - Extra classes appended to the wrapper
+-->
+<script lang="ts" module>
+	/** One option row. `value` is what the control carries: a string, always. */
+	export interface InlineOption {
+		value: string;
+		label: string;
+		disabled?: boolean;
+	}
+</script>
+
+<script lang="ts">
+	import { fly } from 'svelte/transition';
+
+	let {
+		value,
+		options,
+		onchange,
+		onopen,
+		label,
+		class: className = ''
+	}: {
+		value: string;
+		options: readonly InlineOption[];
+		onchange?: (value: string) => void;
+		onopen?: () => void;
+		label?: string;
+		class?: string;
+	} = $props();
+
+	let open = $state(false);
+	let wrapper: HTMLElement | undefined = $state();
+
+	const chosen = $derived(options.find((option) => option.value === value)?.label ?? '');
+
+	function toggle() {
+		if (!open) onopen?.();
+		open = !open;
+	}
+
+	function pick(option: InlineOption) {
+		if (option.disabled) return;
+		open = false;
+		onchange?.(option.value);
+	}
+
+	function onkeydown(event: KeyboardEvent) {
+		if (event.key === 'Escape') {
+			open = false;
+		} else if (event.key === 'ArrowDown' && !open) {
+			event.preventDefault();
+			toggle();
+		}
+	}
+
+	/** Any click that lands outside the control closes it. */
+	function onwindowclick(event: MouseEvent) {
+		if (open && wrapper && !wrapper.contains(event.target as Node)) open = false;
+	}
+</script>
+
+<svelte:window onclick={onwindowclick} />
+
+<span bind:this={wrapper} class="vit-inline-select {className}">
+	<button
+		type="button"
+		class="vit-inline-select__trigger"
+		class:vit-inline-select__trigger--open={open}
+		aria-haspopup="listbox"
+		aria-expanded={open}
+		aria-label={label}
+		onclick={toggle}
+		{onkeydown}
+	>
+		<!-- The trigger is as wide as the CHOSEN label only, so the sentence
+		     reflows as the value changes. The menu carries the widest option. -->
+		<span class="vit-inline-select__value">{chosen}</span>
+		<svg class="vit-inline-select__caret" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+			<path
+				d="M2.5 4.5L6 8L9.5 4.5"
+				stroke="currentColor"
+				stroke-width="1.5"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+			/>
+		</svg>
+	</button>
+
+	{#if open}
+		<ul class="vit-inline-select__menu" role="listbox" transition:fly={{ y: -8, duration: 150 }}>
+			{#each options as option (option.value)}
+				<li
+					role="option"
+					aria-selected={option.value === value}
+					aria-disabled={option.disabled || undefined}
+					class="vit-inline-select__option"
+					class:vit-inline-select__option--chosen={option.value === value}
+					class:vit-inline-select__option--disabled={option.disabled}
+					tabindex={option.disabled ? -1 : 0}
+					onclick={() => pick(option)}
+					onkeydown={(event) => event.key === 'Enter' && pick(option)}
+				>
+					{option.label}
+				</li>
+			{/each}
+		</ul>
+	{/if}
+</span>
+
+<style>
+	.vit-inline-select {
+		position: relative;
+		display: inline-block;
+	}
+
+	.vit-inline-select__trigger {
+		display: inline;
+		padding: 0 0 0.1em;
+		margin: 0;
+		border: 0;
+		border-bottom: 2px solid currentColor;
+		background: transparent;
+		color: inherit;
+		font: inherit;
+		font-weight: var(--vit-madlib-control-weight, 700);
+		cursor: pointer;
+		transition: border-color 200ms;
+	}
+
+	.vit-inline-select__trigger:hover,
+	.vit-inline-select__trigger--open {
+		border-bottom-color: var(--vit-madlib-select-accent, currentColor);
+	}
+
+	.vit-inline-select__value {
+		white-space: nowrap;
+	}
+
+	.vit-inline-select__caret {
+		display: inline;
+		width: 0.5em;
+		height: 0.5em;
+		margin-left: 0.125em;
+		flex-shrink: 0;
+		transition: transform 200ms;
+	}
+
+	.vit-inline-select__trigger--open .vit-inline-select__caret {
+		transform: rotate(180deg);
+	}
+
+	.vit-inline-select__menu {
+		position: absolute;
+		left: 0;
+		z-index: var(--vit-madlib-menu-z, 40);
+		margin: 0.25em 0 0;
+		padding: 0.25em 0;
+		list-style: none;
+		width: max-content;
+		max-width: 42rem;
+		max-height: var(--vit-madlib-menu-max-height, 15rem);
+		overflow: auto;
+		background: var(--vit-madlib-menu-bg, #ffffff);
+		box-shadow: var(--vit-madlib-menu-shadow, none);
+		font: inherit;
+		scrollbar-width: thin;
+	}
+
+	.vit-inline-select__option {
+		padding: 0.375em 1em;
+		font-weight: var(--vit-madlib-control-weight, 700);
+		color: var(--vit-madlib-muted-color, color-mix(in srgb, currentColor 35%, transparent));
+		cursor: pointer;
+		transition: background-color 150ms;
+	}
+
+	.vit-inline-select__option:hover,
+	.vit-inline-select__option:focus-visible {
+		background: var(--vit-madlib-menu-hover, color-mix(in srgb, currentColor 10%, transparent));
+	}
+
+	.vit-inline-select__option--chosen {
+		color: inherit;
+		background: var(--vit-madlib-menu-hover, color-mix(in srgb, currentColor 10%, transparent));
+	}
+
+	.vit-inline-select__option--disabled {
+		opacity: 0.4;
+		pointer-events: none;
+	}
+</style>

package/dist/components/madlib/InlineSelect.svelte.d.ts

@@ -0,0 +1,49 @@
+/** One option row. `value` is what the control carries: a string, always. */
+export interface InlineOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+type $$ComponentProps = {
+    value: string;
+    options: readonly InlineOption[];
+    onchange?: (value: string) => void;
+    onopen?: () => void;
+    label?: string;
+    class?: string;
+};
+/**
+ * InlineSelect
+ *
+ * A select that sits inside running text: the chosen label, underlined, with a
+ * small caret, and a listbox that drops below it. It inherits the font, size
+ * and line-height of the text around it, which is the whole point — a native
+ * `<select>` cannot be made to read as a word in a sentence.
+ *
+ * It is the control `<Madlib>` renders for each blank, and it is exported on
+ * its own for a lone blank in a heading ("Practices in [Spain]").
+ *
+ * ## Theming
+ * Reads the madlib token family, with fallbacks, so it renders standalone:
+ *
+ * | property                       | role                                   |
+ * |--------------------------------|----------------------------------------|
+ * | `--vit-madlib-control-weight`  | weight of the chosen label             |
+ * | `--vit-madlib-muted-color`     | the unchosen options                   |
+ * | `--vit-madlib-select-accent`   | the underline while open or hovered    |
+ * | `--vit-madlib-menu-bg`         | the listbox surface                    |
+ * | `--vit-madlib-menu-hover`      | the option under the pointer / chosen  |
+ * | `--vit-madlib-menu-shadow`     | the listbox shadow                     |
+ * | `--vit-madlib-menu-max-height` | the listbox scroll height              |
+ * | `--vit-madlib-menu-z`          | the listbox stacking order             |
+ *
+ * @property value - The chosen option's value
+ * @property options - The options offered, in order
+ * @property onchange - Fired with the new value when an option is picked
+ * @property onopen - Fired when the listbox is opened, before it shows
+ * @property label - Accessible name for the control, when the surrounding text does not give one
+ * @property class - Extra classes appended to the wrapper
+ */
+declare const InlineSelect: import("svelte").Component<$$ComponentProps, {}, "">;
+type InlineSelect = ReturnType<typeof InlineSelect>;
+export default InlineSelect;

package/dist/components/madlib/Madlib.svelte

@@ -0,0 +1,264 @@
+<!--
+  @component Madlib
+
+  A sentence with blanks, each blank a control: "Show me [open positions] in
+  [Barcelona] over the last [12 months]". The blanks are the levels of a
+  {@link ./sentenceTree} — what a level offers depends on what was chosen
+  above it — and the value is the **path** of chosen ids, root to leaf.
+
+  The component owns nothing but the projection. `walkTree` turns the path into
+  one level per blank; `replaceAt` turns a pick into the next full path,
+  keeping the deeper choices that still apply; the host receives that path in
+  `onchange` and decides what it means. It never holds a copy of the path, so
+  a host that rejects or rewrites a change simply does not pass it back.
+
+  ## Controls
+  Every blank is an {@link ./InlineSelect} unless `controls` says otherwise. A
+  level rendered as a `toggle` lists its options in the text — active one bold
+  and underlined, the others muted, separated by bars — and takes a line of its
+  own together with the text before it, so a two-way branch can read as a
+  headline over the rest of the sentence:
+
+  ```
+  Farming in the  present | future
+  Show me where [all crops] are grown, by [area]
+  ```
+
+  ## Theming
+  CSS custom properties with plain fallbacks; the font, size and weight of the
+  text around each control are inherited by the control:
+
+  | property                        | role                                        |
+  |---------------------------------|---------------------------------------------|
+  | `--vit-madlib-font`             | the sentence's font family                  |
+  | `--vit-madlib-color`            | the sentence's colour                        |
+  | `--vit-madlib-lead-size`        | font size of a toggle's line                |
+  | `--vit-madlib-lead-line-height` | line height of a toggle's line              |
+  | `--vit-madlib-size`             | font size of the dropdown lines             |
+  | `--vit-madlib-line-height`      | line height of the dropdown lines           |
+  | `--vit-madlib-weight`           | weight of the running text                  |
+  | `--vit-madlib-control-weight`   | weight of a chosen option                   |
+  | `--vit-madlib-muted-color`      | unchosen toggle options, bars, menu options |
+  | `--vit-madlib-accent`           | the active toggle option's underline        |
+
+  The `InlineSelect` tokens (`--vit-madlib-select-accent`, `--vit-madlib-menu-*`)
+  apply to every dropdown in the sentence.
+
+  @property tree - The sentence tree
+  @property path - The chosen node ids, root to leaf
+  @property onchange - Fired with the next full path when any blank changes
+  @property controls - How each depth is rendered; `'dropdown'` when omitted
+  @property onopen - Fired when any control is activated, before the change (a
+  host cycling through sentences stops here)
+  @property contentWidth - Bindable: the widest rendered line, in px, remeasured on every change
+  @property class - Extra classes appended to the wrapper
+-->
+<script lang="ts" module>
+	import type { SentenceLevel, SentenceNode } from './sentenceTree.js';
+
+	/** How one level of the sentence is rendered. */
+	export type MadlibControl = 'dropdown' | 'toggle';
+
+	/** Picks the control for a level. Receives the depth and the resolved level. */
+	export type MadlibControls = (depth: number, level: SentenceLevel) => MadlibControl;
+</script>
+
+<script lang="ts">
+	import InlineSelect from './InlineSelect.svelte';
+	import { replaceAt, walkTree } from './sentenceTree.js';
+
+	let {
+		tree,
+		path,
+		onchange,
+		controls,
+		onopen,
+		contentWidth = $bindable(0),
+		class: className = ''
+	}: {
+		tree: SentenceNode;
+		path: readonly string[];
+		onchange: (path: string[]) => void;
+		controls?: MadlibControls;
+		onopen?: () => void;
+		contentWidth?: number;
+		class?: string;
+	} = $props();
+
+	/** One blank of the sentence, with the text that introduces it. */
+	interface Blank {
+		depth: number;
+		level: SentenceLevel;
+		control: MadlibControl;
+		/** The root's label for the first blank, the previous node's connector after. */
+		lead: string | undefined;
+	}
+
+	/** A rendered line: a toggle stands alone on a lead line; dropdowns flow together. */
+	interface Line {
+		kind: 'lead' | 'body';
+		blanks: Blank[];
+	}
+
+	const levels = $derived(walkTree(tree, path));
+
+	const lines = $derived.by((): Line[] => {
+		const out: Line[] = [];
+		levels.forEach((level, depth) => {
+			const blank: Blank = {
+				depth,
+				level,
+				control: controls?.(depth, level) ?? 'dropdown',
+				lead: depth === 0 ? tree.label : levels[depth - 1].node.connector
+			};
+			const last = out[out.length - 1];
+			if (blank.control === 'toggle') out.push({ kind: 'lead', blanks: [blank] });
+			else if (last?.kind === 'body') last.blanks.push(blank);
+			else out.push({ kind: 'body', blanks: [blank] });
+		});
+		return out;
+	});
+
+	/**
+	 * A leaf's own `connector` has no next control to introduce, so it trails
+	 * the sentence rather than being dropped.
+	 */
+	const trailing = $derived.by(() => {
+		const last = levels[levels.length - 1];
+		return last && !last.node.children?.length ? last.node.connector : undefined;
+	});
+
+	let root: HTMLElement | undefined = $state();
+
+	/**
+	 * The space between a control and the text after it — none when that text
+	 * opens with punctuation (", under a" hugs the control it follows).
+	 * @param text - The connector or leading text about to be rendered
+	 * @returns A single space, or nothing before punctuation
+	 */
+	const gap = (text: string) => (/^[,.;:!?)]/.test(text) ? '' : ' ');
+
+	function pick(depth: number, id: string) {
+		onchange(replaceAt(tree, path, depth, id));
+	}
+
+	function activate(depth: number, id: string) {
+		onopen?.();
+		pick(depth, id);
+	}
+
+	/**
+	 * The widest rendered line: inline rects grouped by their row. A host
+	 * aligning something under the sentence (a legend, a caption) wants the
+	 * text's width, not the block's.
+	 */
+	function measure() {
+		if (!root) return;
+		const range = document.createRange();
+		range.selectNodeContents(root);
+		const left = root.getBoundingClientRect().left;
+		const rows: Record<number, number> = {};
+		for (const rect of range.getClientRects()) {
+			const row = Math.round(rect.top);
+			rows[row] = Math.max(rows[row] ?? 0, rect.right - left);
+		}
+		contentWidth = Math.ceil(Math.max(0, ...Object.values(rows)));
+	}
+
+	$effect(() => {
+		void path;
+		const frame = requestAnimationFrame(measure);
+		return () => cancelAnimationFrame(frame);
+	});
+</script>
+
+<div bind:this={root} class="vit-madlib {className}">
+	{#if levels.length === 0}
+		<span class="vit-madlib__line vit-madlib__line--lead">{tree.label}</span>
+	{/if}
+	{#each lines as line, i (i)}
+		<span class="vit-madlib__line vit-madlib__line--{line.kind}">
+			{#each line.blanks as blank (blank.depth)}
+				{#if blank.lead}<span class="vit-madlib__text">{`${gap(blank.lead)}${blank.lead} `}</span
+					>{/if}
+				{#if blank.control === 'toggle'}
+					{#each blank.level.siblings as option, j (option.id)}
+						{#if j > 0}<span class="vit-madlib__separator" aria-hidden="true">|</span>{/if}
+						<button
+							type="button"
+							class="vit-madlib__toggle"
+							class:vit-madlib__toggle--active={option.id === blank.level.node.id}
+							aria-pressed={option.id === blank.level.node.id}
+							onclick={() => activate(blank.depth, option.id)}
+						>
+							{option.label}
+						</button>
+					{/each}
+				{:else}
+					<InlineSelect
+						value={blank.level.node.id}
+						options={blank.level.siblings.map((s) => ({ value: s.id, label: s.label }))}
+						onchange={(id) => pick(blank.depth, id)}
+						{onopen}
+					/>
+				{/if}
+			{/each}
+			{#if line === lines[lines.length - 1] && trailing}
+				<span class="vit-madlib__text">{`${gap(trailing)}${trailing}`}</span>
+			{/if}
+		</span>
+	{/each}
+</div>
+
+<style>
+	.vit-madlib {
+		font-family: var(--vit-madlib-font, inherit);
+		color: var(--vit-madlib-color, inherit);
+		font-weight: var(--vit-madlib-weight, inherit);
+		text-wrap: balance;
+	}
+
+	.vit-madlib__line {
+		display: block;
+	}
+
+	.vit-madlib__line--lead {
+		font-size: var(--vit-madlib-lead-size, 1em);
+		line-height: var(--vit-madlib-lead-line-height, 1.4);
+	}
+
+	.vit-madlib__line--body {
+		font-size: var(--vit-madlib-size, 1em);
+		line-height: var(--vit-madlib-line-height, 1.4);
+	}
+
+	.vit-madlib__separator {
+		padding: 0 0.375em;
+		color: var(--vit-madlib-muted-color, color-mix(in srgb, currentColor 35%, transparent));
+	}
+
+	.vit-madlib__toggle {
+		padding: 0 0 0.125em;
+		margin: 0;
+		border: 0;
+		border-bottom: 2px solid transparent;
+		background: transparent;
+		font: inherit;
+		color: var(--vit-madlib-muted-color, color-mix(in srgb, currentColor 35%, transparent));
+		cursor: pointer;
+		transition: color 200ms;
+	}
+
+	.vit-madlib__toggle:hover {
+		color: inherit;
+		opacity: 0.6;
+	}
+
+	.vit-madlib__toggle--active,
+	.vit-madlib__toggle--active:hover {
+		color: inherit;
+		opacity: 1;
+		font-weight: var(--vit-madlib-control-weight, 700);
+		border-bottom-color: var(--vit-madlib-accent, currentColor);
+	}
+</style>

package/dist/components/madlib/Madlib.svelte.d.ts

@@ -0,0 +1,72 @@
+import type { SentenceLevel, SentenceNode } from './sentenceTree.js';
+/** How one level of the sentence is rendered. */
+export type MadlibControl = 'dropdown' | 'toggle';
+/** Picks the control for a level. Receives the depth and the resolved level. */
+export type MadlibControls = (depth: number, level: SentenceLevel) => MadlibControl;
+type $$ComponentProps = {
+    tree: SentenceNode;
+    path: readonly string[];
+    onchange: (path: string[]) => void;
+    controls?: MadlibControls;
+    onopen?: () => void;
+    contentWidth?: number;
+    class?: string;
+};
+/**
+ * Madlib
+ *
+ * A sentence with blanks, each blank a control: "Show me [open positions] in
+ * [Barcelona] over the last [12 months]". The blanks are the levels of a
+ * {@link ./sentenceTree} — what a level offers depends on what was chosen
+ * above it — and the value is the **path** of chosen ids, root to leaf.
+ *
+ * The component owns nothing but the projection. `walkTree` turns the path into
+ * one level per blank; `replaceAt` turns a pick into the next full path,
+ * keeping the deeper choices that still apply; the host receives that path in
+ * `onchange` and decides what it means. It never holds a copy of the path, so
+ * a host that rejects or rewrites a change simply does not pass it back.
+ *
+ * ## Controls
+ * Every blank is an {@link ./InlineSelect} unless `controls` says otherwise. A
+ * level rendered as a `toggle` lists its options in the text — active one bold
+ * and underlined, the others muted, separated by bars — and takes a line of its
+ * own together with the text before it, so a two-way branch can read as a
+ * headline over the rest of the sentence:
+ *
+ * ```
+ * Farming in the  present | future
+ * Show me where [all crops] are grown, by [area]
+ * ```
+ *
+ * ## Theming
+ * CSS custom properties with plain fallbacks; the font, size and weight of the
+ * text around each control are inherited by the control:
+ *
+ * | property                        | role                                        |
+ * |---------------------------------|---------------------------------------------|
+ * | `--vit-madlib-font`             | the sentence's font family                  |
+ * | `--vit-madlib-color`            | the sentence's colour                        |
+ * | `--vit-madlib-lead-size`        | font size of a toggle's line                |
+ * | `--vit-madlib-lead-line-height` | line height of a toggle's line              |
+ * | `--vit-madlib-size`             | font size of the dropdown lines             |
+ * | `--vit-madlib-line-height`      | line height of the dropdown lines           |
+ * | `--vit-madlib-weight`           | weight of the running text                  |
+ * | `--vit-madlib-control-weight`   | weight of a chosen option                   |
+ * | `--vit-madlib-muted-color`      | unchosen toggle options, bars, menu options |
+ * | `--vit-madlib-accent`           | the active toggle option's underline        |
+ *
+ * The `InlineSelect` tokens (`--vit-madlib-select-accent`, `--vit-madlib-menu-*`)
+ * apply to every dropdown in the sentence.
+ *
+ * @property tree - The sentence tree
+ * @property path - The chosen node ids, root to leaf
+ * @property onchange - Fired with the next full path when any blank changes
+ * @property controls - How each depth is rendered; `'dropdown'` when omitted
+ * @property onopen - Fired when any control is activated, before the change (a
+ * host cycling through sentences stops here)
+ * @property contentWidth - Bindable: the widest rendered line, in px, remeasured on every change
+ * @property class - Extra classes appended to the wrapper
+ */
+declare const Madlib: import("svelte").Component<$$ComponentProps, {}, "contentWidth">;
+type Madlib = ReturnType<typeof Madlib>;
+export default Madlib;

package/dist/components/madlib/sentenceTree.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The sentence tree: the data behind a madlib, and the path arithmetic on it.
+ *
+ * A madlib is a sentence with blanks — "Show me [open positions] in
+ * [Barcelona] over the last [12 months]" — where each blank is one level of a
+ * tree and the options offered at a level are the children of what was picked
+ * at the level above. A selection is therefore a **path**: one node id per
+ * level, root to leaf. Everything the component does is arithmetic on that
+ * path, so it lives here, pure and tested, and `<Madlib>` only projects it.
+ *
+ * The tree is plain data. `label` is what a node reads as when it is the
+ * chosen option; `connector` is the text that follows it before the next
+ * blank; the root's `label` is the sentence's leading text. Nothing here
+ * knows what a path *means* — that is the host's mapping, on the way out.
+ */
+/**
+ * One node of a sentence tree.
+ *
+ * @property id - Unique among its siblings; the path carries these
+ * @property label - What the option reads as, in the control and in the sentence
+ * @property connector - Text after this node's control, before the next one. On a
+ * leaf it trails the sentence instead, since there is no next control
+ * @property children - The next level's options. A node without children is a leaf
+ */
+export interface SentenceNode {
+    id: string;
+    label: string;
+    connector?: string;
+    children?: SentenceNode[];
+}
+/** One resolved level of a path: the node chosen there, and every option it was chosen from. */
+export interface SentenceLevel {
+    node: SentenceNode;
+    siblings: SentenceNode[];
+}
+/**
+ * Resolves a path against the tree, one level per id, stopping at the first
+ * id that is not a child of the level above (or at a leaf). The result is what
+ * a control per level needs: the chosen node and its siblings.
+ *
+ * @param tree - The root node
+ * @param path - Node ids, root to leaf
+ * @returns One entry per resolved level, possibly fewer than `path.length`
+ *
+ * @example
+ * walkTree(tree, ['jobs', 'bcn'])
+ * // → [{ node: jobs, siblings: [jobs, projects] }, { node: bcn, siblings: [bcn, remote] }]
+ */
+export declare function walkTree(tree: SentenceNode, path: readonly string[]): SentenceLevel[];
+/**
+ * Completes a partial path down to a leaf by taking the first child at every
+ * remaining level. The prefix is kept as far as it resolves; from the first
+ * id that does not, the defaults take over. `completePath(tree, [])` is the
+ * tree's default sentence.
+ *
+ * @param tree - The root node
+ * @param partial - Leading node ids, possibly empty, possibly partly invalid
+ * @returns A full root-to-leaf path
+ */
+export declare function completePath(tree: SentenceNode, partial: readonly string[]): string[];
+/**
+ * The tree's default sentence: first child at every level.
+ *
+ * @param tree - The root node
+ * @returns A full root-to-leaf path, empty for a tree with no children
+ */
+export declare function defaultPath(tree: SentenceNode): string[];
+/**
+ * Changes one level of a path and re-completes everything below it.
+ *
+ * Levels above `depth` are kept. Below it, each level prefers the id the
+ * previous path had at that same depth when it is still a valid option there
+ * — so switching "maize" to "wheat" keeps "by area" — and falls back to the
+ * first child when it is not, which is what happens across a branch change or
+ * when the levels shift.
+ *
+ * @param tree - The root node
+ * @param path - The current path
+ * @param depth - Index of the level being changed
+ * @param id - The new node id at that level
+ * @returns A full root-to-leaf path
+ */
+export declare function replaceAt(tree: SentenceNode, path: readonly string[], depth: number, id: string): string[];
+/**
+ * Every root-to-leaf path, depth first, in the order the tree declares them.
+ * A host uses it to cycle through all sentences, or to check that each one
+ * resolves to something.
+ *
+ * @param tree - The root node
+ * @returns All full paths; `[[]]` for a tree with no children
+ */
+export declare function leafPaths(tree: SentenceNode): string[][];

package/dist/components/madlib/sentenceTree.js

@@ -0,0 +1,140 @@
+/**
+ * The sentence tree: the data behind a madlib, and the path arithmetic on it.
+ *
+ * A madlib is a sentence with blanks — "Show me [open positions] in
+ * [Barcelona] over the last [12 months]" — where each blank is one level of a
+ * tree and the options offered at a level are the children of what was picked
+ * at the level above. A selection is therefore a **path**: one node id per
+ * level, root to leaf. Everything the component does is arithmetic on that
+ * path, so it lives here, pure and tested, and `<Madlib>` only projects it.
+ *
+ * The tree is plain data. `label` is what a node reads as when it is the
+ * chosen option; `connector` is the text that follows it before the next
+ * blank; the root's `label` is the sentence's leading text. Nothing here
+ * knows what a path *means* — that is the host's mapping, on the way out.
+ */
+/** The child of `node` with this id, or undefined — a leaf has none. */
+function childOf(node, id) {
+    return node.children?.find((child) => child.id === id);
+}
+/** Whether `node` still has a level below it. */
+function hasChildren(node) {
+    return node.children !== undefined && node.children.length > 0;
+}
+/**
+ * Resolves a path against the tree, one level per id, stopping at the first
+ * id that is not a child of the level above (or at a leaf). The result is what
+ * a control per level needs: the chosen node and its siblings.
+ *
+ * @param tree - The root node
+ * @param path - Node ids, root to leaf
+ * @returns One entry per resolved level, possibly fewer than `path.length`
+ *
+ * @example
+ * walkTree(tree, ['jobs', 'bcn'])
+ * // → [{ node: jobs, siblings: [jobs, projects] }, { node: bcn, siblings: [bcn, remote] }]
+ */
+export function walkTree(tree, path) {
+    const levels = [];
+    let current = tree;
+    for (const id of path) {
+        if (!current.children)
+            break;
+        const match = childOf(current, id);
+        if (!match)
+            break;
+        levels.push({ node: match, siblings: current.children });
+        current = match;
+    }
+    return levels;
+}
+/**
+ * Completes a partial path down to a leaf by taking the first child at every
+ * remaining level. The prefix is kept as far as it resolves; from the first
+ * id that does not, the defaults take over. `completePath(tree, [])` is the
+ * tree's default sentence.
+ *
+ * @param tree - The root node
+ * @param partial - Leading node ids, possibly empty, possibly partly invalid
+ * @returns A full root-to-leaf path
+ */
+export function completePath(tree, partial) {
+    const path = [];
+    let current = tree;
+    for (const id of partial) {
+        const match = childOf(current, id);
+        if (!match)
+            break;
+        path.push(id);
+        current = match;
+    }
+    while (hasChildren(current)) {
+        const first = current.children[0];
+        path.push(first.id);
+        current = first;
+    }
+    return path;
+}
+/**
+ * The tree's default sentence: first child at every level.
+ *
+ * @param tree - The root node
+ * @returns A full root-to-leaf path, empty for a tree with no children
+ */
+export function defaultPath(tree) {
+    return completePath(tree, []);
+}
+/**
+ * Changes one level of a path and re-completes everything below it.
+ *
+ * Levels above `depth` are kept. Below it, each level prefers the id the
+ * previous path had at that same depth when it is still a valid option there
+ * — so switching "maize" to "wheat" keeps "by area" — and falls back to the
+ * first child when it is not, which is what happens across a branch change or
+ * when the levels shift.
+ *
+ * @param tree - The root node
+ * @param path - The current path
+ * @param depth - Index of the level being changed
+ * @param id - The new node id at that level
+ * @returns A full root-to-leaf path
+ */
+export function replaceAt(tree, path, depth, id) {
+    const next = [...path.slice(0, depth), id];
+    let current = tree;
+    for (const step of next) {
+        const match = childOf(current, step);
+        if (!match)
+            break;
+        current = match;
+    }
+    while (hasChildren(current)) {
+        const previous = path[next.length];
+        const kept = previous === undefined ? undefined : childOf(current, previous);
+        const chosen = kept ?? current.children[0];
+        next.push(chosen.id);
+        current = chosen;
+    }
+    return next;
+}
+/**
+ * Every root-to-leaf path, depth first, in the order the tree declares them.
+ * A host uses it to cycle through all sentences, or to check that each one
+ * resolves to something.
+ *
+ * @param tree - The root node
+ * @returns All full paths; `[[]]` for a tree with no children
+ */
+export function leafPaths(tree) {
+    const paths = [];
+    const visit = (node, prefix) => {
+        if (!hasChildren(node)) {
+            paths.push(prefix);
+            return;
+        }
+        for (const child of node.children)
+            visit(child, [...prefix, child.id]);
+    };
+    visit(tree, []);
+    return paths;
+}

package/dist/components/overlay/HoverCard.svelte

@@ -0,0 +1,138 @@
+<!--
+  @component HoverCard
+
+  The chrome of a hover card: a fixed-width surface with a shimmer skeleton
+  while its content is still resolving.
+
+  It owns the *shell*, never the content — what goes inside is the host's
+  snippet. It pairs with {@link ./anchor}, which decides where it goes, and the
+  two are separate on purpose: placement is arithmetic a test can check, chrome
+  is CSS a test cannot.
+
+  ## Why the shimmer is here
+  A hover card whose content arrives asynchronously flickers between empty and
+  full. Showing a skeleton for a beat makes the transition deliberate, and doing
+  it on *every* new target rather than only on slow ones keeps the rhythm
+  even — a card that sometimes shimmers and sometimes does not reads as jank.
+  Remount the component (a `{#key}` on the hovered target) and it shimmers
+  again; pass `skipShimmer` for a clone that is animating out, which should fade
+  real content rather than a fresh skeleton.
+
+  ## Theming
+  Presentation is CSS custom properties with plain fallbacks, so the card
+  renders standalone and restyles without a CSS framework:
+
+  | property                   | default   |
+  |----------------------------|-----------|
+  | `--vit-card-font`          | `inherit` |
+  | `--vit-card-width`         | `277px`   |
+  | `--vit-card-padding`       | `10px`    |
+  | `--vit-card-gap`           | `10px`    |
+  | `--vit-card-bg`            | `#ffffff` |
+  | `--vit-card-radius`        | `0`       |
+  | `--vit-card-shadow`        | `none`    |
+  | `--vit-card-shimmer-color` | `currentColor` |
+
+  @property skipShimmer - Suppresses the mount shimmer, for a card fading out
+  @property shimmerMs - How long the skeleton is held, in ms
+  @property lines - Skeleton rows drawn under the heading block
+  @property class - Extra classes appended to the card
+  @property children - The card's content
+-->
+<script lang="ts">
+	import { onMount, type Snippet } from 'svelte';
+
+	let {
+		skipShimmer = false,
+		shimmerMs = 150,
+		lines = 3,
+		class: className = '',
+		children
+	}: {
+		skipShimmer?: boolean;
+		shimmerMs?: number;
+		lines?: number;
+		class?: string;
+		children: Snippet;
+	} = $props();
+
+	// Fixed per mount — the leaving clone must never re-shimmer.
+	// svelte-ignore state_referenced_locally
+	let shimmer = $state(!skipShimmer);
+
+	onMount(() => {
+		if (!shimmer) return;
+		const t = setTimeout(() => (shimmer = false), shimmerMs);
+		return () => clearTimeout(t);
+	});
+
+	/** Descending widths, so the skeleton reads as text rather than as bars. */
+	const widths = $derived(Array.from({ length: Math.max(0, lines) }, (_, i) => `${100 - i * 25}%`));
+</script>
+
+<div class="vit-card {className}">
+	{#if shimmer}
+		<div class="vit-card__skeleton">
+			<span class="vit-card__line" style="height: 12px; width: 100%"></span>
+			<span class="vit-card__line" style="height: 8px; width: 5rem"></span>
+			<span class="vit-card__rows">
+				{#each widths as w, i (i)}
+					<span class="vit-card__line" style="height: 17px; width: {w}"></span>
+				{/each}
+			</span>
+		</div>
+	{:else}
+		{@render children()}
+	{/if}
+</div>
+
+<style>
+	.vit-card {
+		display: flex;
+		flex-direction: column;
+		gap: var(--vit-card-gap, 10px);
+		width: var(--vit-card-width, 277px);
+		padding: var(--vit-card-padding, 10px);
+		overflow: hidden;
+		background: var(--vit-card-bg, #ffffff);
+		border-radius: var(--vit-card-radius, 0);
+		box-shadow: var(--vit-card-shadow, none);
+		font-family: var(--vit-card-font, inherit);
+	}
+	.vit-card__skeleton {
+		display: flex;
+		flex-direction: column;
+		gap: 6px;
+	}
+	.vit-card__rows {
+		display: flex;
+		flex-direction: column;
+		gap: 4px;
+		margin-top: 8px;
+	}
+	.vit-card__line {
+		display: block;
+		border-radius: 2px;
+		background: var(--vit-card-shimmer-color, currentColor);
+		animation: vit-card-shimmer 400ms ease-in-out infinite;
+	}
+
+	@keyframes vit-card-shimmer {
+		0% {
+			opacity: 0.3;
+		}
+		50% {
+			opacity: 0.6;
+		}
+		100% {
+			opacity: 0.3;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.vit-card__line {
+			animation: none;
+			opacity: 0.3;
+		}
+	}
+</style>

package/dist/components/overlay/HoverCard.svelte.d.ts

@@ -0,0 +1,52 @@
+import { type Snippet } from 'svelte';
+type $$ComponentProps = {
+    skipShimmer?: boolean;
+    shimmerMs?: number;
+    lines?: number;
+    class?: string;
+    children: Snippet;
+};
+/**
+ * HoverCard
+ *
+ * The chrome of a hover card: a fixed-width surface with a shimmer skeleton
+ * while its content is still resolving.
+ *
+ * It owns the *shell*, never the content — what goes inside is the host's
+ * snippet. It pairs with {@link ./anchor}, which decides where it goes, and the
+ * two are separate on purpose: placement is arithmetic a test can check, chrome
+ * is CSS a test cannot.
+ *
+ * ## Why the shimmer is here
+ * A hover card whose content arrives asynchronously flickers between empty and
+ * full. Showing a skeleton for a beat makes the transition deliberate, and doing
+ * it on *every* new target rather than only on slow ones keeps the rhythm
+ * even — a card that sometimes shimmers and sometimes does not reads as jank.
+ * Remount the component (a `{#key}` on the hovered target) and it shimmers
+ * again; pass `skipShimmer` for a clone that is animating out, which should fade
+ * real content rather than a fresh skeleton.
+ *
+ * ## Theming
+ * Presentation is CSS custom properties with plain fallbacks, so the card
+ * renders standalone and restyles without a CSS framework:
+ *
+ * | property                   | default   |
+ * |----------------------------|-----------|
+ * | `--vit-card-font`          | `inherit` |
+ * | `--vit-card-width`         | `277px`   |
+ * | `--vit-card-padding`       | `10px`    |
+ * | `--vit-card-gap`           | `10px`    |
+ * | `--vit-card-bg`            | `#ffffff` |
+ * | `--vit-card-radius`        | `0`       |
+ * | `--vit-card-shadow`        | `none`    |
+ * | `--vit-card-shimmer-color` | `currentColor` |
+ *
+ * @property skipShimmer - Suppresses the mount shimmer, for a card fading out
+ * @property shimmerMs - How long the skeleton is held, in ms
+ * @property lines - Skeleton rows drawn under the heading block
+ * @property class - Extra classes appended to the card
+ * @property children - The card's content
+ */
+declare const HoverCard: import("svelte").Component<$$ComponentProps, {}, "">;
+type HoverCard = ReturnType<typeof HoverCard>;
+export default HoverCard;

package/dist/components/overlay/anchor.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @module components/overlay/anchor
+ * Where a floating card goes when it is attached to a point.
+ *
+ * "Put a card next to the pointer without letting it leave the container" is a
+ * rule every hover tooltip needs and nobody writes down. It gets re-derived at
+ * each call site, slightly differently each time, and because it only runs
+ * inside a live layout it is never tested — so the version that forgot to clamp
+ * vertically ships a card that falls off the bottom of a short viewport, and
+ * nobody notices until a phone does it.
+ *
+ * It is one function here, it takes measurements rather than elements, and it
+ * returns two numbers. No DOM, no framework, no CSS: the caller owns all three.
+ */
+/** The point the card is attached to, in container coordinates. */
+export type AnchorPoint = {
+    /** Distance from the container's left edge, in px. */
+    x: number;
+    /** Distance from the container's top edge, in px. */
+    y: number;
+};
+/** A measured rectangle, in px. */
+export type AnchorBox = {
+    /** Width in px. */
+    width: number;
+    /** Height in px. */
+    height: number;
+};
+/** Space to keep between the card and each container edge, in px. */
+export type AnchorPadding = {
+    /** Minimum gap above the card. */
+    top?: number;
+    /** Minimum gap to the right of the card. */
+    right?: number;
+    /** Minimum gap below the card. */
+    bottom?: number;
+    /** Minimum gap to the left of the card. */
+    left?: number;
+};
+/** How the card is placed relative to the point, before clamping. */
+export type AnchorOptions = {
+    /**
+     * Gap between the point and the card's near edge, in px. `x` is the
+     * horizontal offset to whichever side the card lands on; `y` shifts the
+     * card vertically and is only read when `align` is `'start'`.
+     */
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    /**
+     * Vertical relationship to the point: `'center'` centres the card on it,
+     * `'start'` puts the card's top edge there (plus `offset.y`).
+     */
+    align?: 'center' | 'start';
+    /** Minimum gaps from the container edges. */
+    padding?: AnchorPadding;
+    /**
+     * When the card does not fit on its preferred side, put it on the other one
+     * instead of letting the clamp slide it back over the point. Leave it off
+     * for a card that should simply stay put.
+     */
+    flip?: boolean;
+    /** Preferred horizontal side. Default `'right'`. */
+    side?: 'right' | 'left';
+};
+/** The resolved position, ready to write to `left` / `top` in px. */
+export type AnchorPosition = {
+    /** Distance from the container's left edge, in px. */
+    left: number;
+    /** Distance from the container's top edge, in px. */
+    top: number;
+};
+/**
+ * Places a card beside a point, kept inside its container.
+ *
+ * The card is laid out on its preferred side, optionally flipped to the other
+ * side when it would not fit, and then clamped on **both** axes so it can never
+ * cross the container's padding — including vertically, which is the half most
+ * hand-rolled versions leave out.
+ *
+ * A container with no measured size yet (width or height `0`) returns the raw
+ * point, so a first frame renders somewhere sensible rather than at `0,0`.
+ *
+ * @param point - Where the card is attached, in container coordinates.
+ * @param card - The card's measured size. Height may be an estimate on the
+ *   first frame; re-running once it is measured is cheap and exact.
+ * @param container - The box the card must stay inside.
+ * @param options - Offset, alignment, padding, flipping and preferred side.
+ * @returns The `left` / `top` to position the card at, in px.
+ */
+export declare function anchor(point: AnchorPoint, card: AnchorBox, container: AnchorBox, options?: AnchorOptions): AnchorPosition;

package/dist/components/overlay/anchor.js

@@ -0,0 +1,61 @@
+/**
+ * @module components/overlay/anchor
+ * Where a floating card goes when it is attached to a point.
+ *
+ * "Put a card next to the pointer without letting it leave the container" is a
+ * rule every hover tooltip needs and nobody writes down. It gets re-derived at
+ * each call site, slightly differently each time, and because it only runs
+ * inside a live layout it is never tested — so the version that forgot to clamp
+ * vertically ships a card that falls off the bottom of a short viewport, and
+ * nobody notices until a phone does it.
+ *
+ * It is one function here, it takes measurements rather than elements, and it
+ * returns two numbers. No DOM, no framework, no CSS: the caller owns all three.
+ */
+/**
+ * Places a card beside a point, kept inside its container.
+ *
+ * The card is laid out on its preferred side, optionally flipped to the other
+ * side when it would not fit, and then clamped on **both** axes so it can never
+ * cross the container's padding — including vertically, which is the half most
+ * hand-rolled versions leave out.
+ *
+ * A container with no measured size yet (width or height `0`) returns the raw
+ * point, so a first frame renders somewhere sensible rather than at `0,0`.
+ *
+ * @param point - Where the card is attached, in container coordinates.
+ * @param card - The card's measured size. Height may be an estimate on the
+ *   first frame; re-running once it is measured is cheap and exact.
+ * @param container - The box the card must stay inside.
+ * @param options - Offset, alignment, padding, flipping and preferred side.
+ * @returns The `left` / `top` to position the card at, in px.
+ */
+export function anchor(point, card, container, options = {}) {
+    if (!container.width || !container.height)
+        return { left: point.x, top: point.y };
+    const offsetX = options.offset?.x ?? 16;
+    const offsetY = options.offset?.y ?? 0;
+    const padTop = options.padding?.top ?? 0;
+    const padRight = options.padding?.right ?? 0;
+    const padBottom = options.padding?.bottom ?? 0;
+    const padLeft = options.padding?.left ?? 0;
+    const toLeftOf = point.x - offsetX - card.width;
+    const toRightOf = point.x + offsetX;
+    let left = options.side === 'left' ? toLeftOf : toRightOf;
+    if (options.flip) {
+        if (options.side === 'left') {
+            if (left < padLeft && toRightOf + card.width <= container.width - padRight)
+                left = toRightOf;
+        }
+        else if (left + card.width > container.width - padRight && toLeftOf >= padLeft) {
+            left = toLeftOf;
+        }
+    }
+    let top = options.align === 'start' ? point.y + offsetY : point.y - card.height / 2;
+    // Clamp last, on both axes. `Math.max` after `Math.min` so a card taller or
+    // wider than the space it has left is pinned to the near edge rather than
+    // pushed off the far one.
+    left = Math.max(padLeft, Math.min(left, container.width - card.width - padRight));
+    top = Math.max(padTop, Math.min(top, container.height - card.height - padBottom));
+    return { left, top };
+}

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export * from './forms/index.js';
 export * from './config/index.js';
 export * from './edit/index.js';
 export { buildQueryString } from './utils/paths.js';
+export { anchor, HoverCard } from './overlay.js';

package/dist/index.js

@@ -16,3 +16,4 @@ export * from './edit/index.js';
 // server-side rules, so they go through ./contract instead — see the note in
 // utils/paths.ts, which is where the export surface for all of them is decided.
 export { buildQueryString } from './utils/paths.js';
+export { anchor, HoverCard } from './overlay.js';

package/dist/madlib.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The madlib: a sentence with blanks, where each blank is a level of a tree
+ * and the value is the path of chosen ids. `<Madlib>` renders one; the tree
+ * helpers are the arithmetic it is a projection of, exported so a host can
+ * complete a deep link, enumerate every sentence, or drive a second control
+ * off the same tree. `<InlineSelect>` is the blank on its own, for a lone
+ * choice inside a heading.
+ *
+ * Domain-free: it knows ids, labels and connectors, and nothing about what a
+ * path means. Themed with `--vit-madlib-*` custom properties rather than
+ * utility classes, and not re-exported from the package root.
+ */
+export { default as Madlib } from './components/madlib/Madlib.svelte';
+export type { MadlibControl, MadlibControls } from './components/madlib/Madlib.svelte';
+export { default as InlineSelect } from './components/madlib/InlineSelect.svelte';
+export type { InlineOption } from './components/madlib/InlineSelect.svelte';
+export { completePath, defaultPath, leafPaths, replaceAt, walkTree, type SentenceLevel, type SentenceNode } from './components/madlib/sentenceTree.js';

package/dist/madlib.js

@@ -0,0 +1,15 @@
+/**
+ * The madlib: a sentence with blanks, where each blank is a level of a tree
+ * and the value is the path of chosen ids. `<Madlib>` renders one; the tree
+ * helpers are the arithmetic it is a projection of, exported so a host can
+ * complete a deep link, enumerate every sentence, or drive a second control
+ * off the same tree. `<InlineSelect>` is the blank on its own, for a lone
+ * choice inside a heading.
+ *
+ * Domain-free: it knows ids, labels and connectors, and nothing about what a
+ * path means. Themed with `--vit-madlib-*` custom properties rather than
+ * utility classes, and not re-exported from the package root.
+ */
+export { default as Madlib } from './components/madlib/Madlib.svelte';
+export { default as InlineSelect } from './components/madlib/InlineSelect.svelte';
+export { completePath, defaultPath, leafPaths, replaceAt, walkTree } from './components/madlib/sentenceTree.js';

package/dist/overlay.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Floating-overlay primitives: where a card attached to a point goes, and the
+ * chrome it is drawn in.
+ *
+ * The two are separate because they fail differently. Placement is arithmetic —
+ * it can be wrong on a phone and right on a laptop, and it belongs in a test.
+ * Chrome is CSS, and belongs behind custom properties. Both were previously
+ * re-implemented per call site, which is how one copy ended up clamping
+ * horizontally but not vertically.
+ *
+ * Domain-free: it knows about points, boxes and padding, and nothing about maps,
+ * charts or what the card says.
+ */
+export { anchor, type AnchorBox, type AnchorOptions, type AnchorPadding, type AnchorPoint, type AnchorPosition } from './components/overlay/anchor.js';
+export { default as HoverCard } from './components/overlay/HoverCard.svelte';

package/dist/overlay.js

@@ -0,0 +1,15 @@
+/**
+ * Floating-overlay primitives: where a card attached to a point goes, and the
+ * chrome it is drawn in.
+ *
+ * The two are separate because they fail differently. Placement is arithmetic —
+ * it can be wrong on a phone and right on a laptop, and it belongs in a test.
+ * Chrome is CSS, and belongs behind custom properties. Both were previously
+ * re-implemented per call site, which is how one copy ended up clamping
+ * horizontally but not vertically.
+ *
+ * Domain-free: it knows about points, boxes and padding, and nothing about maps,
+ * charts or what the card says.
+ */
+export { anchor } from './components/overlay/anchor.js';
+export { default as HoverCard } from './components/overlay/HoverCard.svelte';

package/dist/styles/tokens.css

@@ -79,4 +79,40 @@
 	--video-badge-padding: var(--space-3);
 	--video-badge-color: var(--color-ink);
 	--video-badge-bg: rgb(255 255 255 / 50%);
+
+	/* Floating overlays (the `./overlay` subpath) */
+	/* The hover card's fixed width. Fixed rather than fluid because the card is
+	   positioned by measuring it: a width that depends on its content makes the
+	   placement arithmetic chase itself for a frame. */
+	--vit-card-width: 277px;
+	--vit-card-padding: var(--space-2, 10px);
+	--vit-card-gap: var(--space-2, 10px);
+	--vit-card-bg: #ffffff;
+	--vit-card-radius: 0;
+	--vit-card-shadow: none;
+	--vit-card-font: inherit;
+	--vit-card-shimmer-color: currentColor;
+
+	/* Madlib (`./madlib`): a sentence with blanks. The controls inherit the
+	   font, size and weight of the text around them, so most of these default
+	   to "whatever the sentence is"; the menu and the accents are the ones a
+	   theme sets. `--vit-madlib-select-accent` follows `--vit-madlib-accent`
+	   unless a theme wants the dropdown underline and the toggle underline to
+	   differ, which the first host did. */
+	--vit-madlib-font: inherit;
+	--vit-madlib-color: inherit;
+	--vit-madlib-weight: inherit;
+	--vit-madlib-control-weight: 700;
+	--vit-madlib-lead-size: 1em;
+	--vit-madlib-lead-line-height: 1.4;
+	--vit-madlib-size: 1em;
+	--vit-madlib-line-height: 1.4;
+	--vit-madlib-muted-color: color-mix(in srgb, currentColor 35%, transparent);
+	--vit-madlib-accent: currentColor;
+	--vit-madlib-select-accent: var(--vit-madlib-accent);
+	--vit-madlib-menu-bg: var(--color-surface);
+	--vit-madlib-menu-hover: color-mix(in srgb, currentColor 10%, transparent);
+	--vit-madlib-menu-shadow: none;
+	--vit-madlib-menu-max-height: 15rem;
+	--vit-madlib-menu-z: 40;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vit-foundation/ui",
-	"version": "0.30.0",
+	"version": "0.32.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -96,6 +96,16 @@
 			"types": "./dist/scrolly.d.ts",
 			"svelte": "./dist/scrolly.js",
 			"default": "./dist/scrolly.js"
+		},
+		"./overlay": {
+			"types": "./dist/overlay.d.ts",
+			"svelte": "./dist/overlay.js",
+			"default": "./dist/overlay.js"
+		},
+		"./madlib": {
+			"types": "./dist/madlib.d.ts",
+			"svelte": "./dist/madlib.js",
+			"default": "./dist/madlib.js"
 		}
 	},
 	"peerDependencies": {