@vit-foundation/ui 0.31.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/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/styles/tokens.css

@@ -92,4 +92,27 @@
 	--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.31.0",
+	"version": "0.32.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -101,6 +101,11 @@
 			"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": {