@vit-foundation/ui 0.28.0 → 0.30.0

package/README.md

@@ -9,7 +9,10 @@ content editable in place.
 npm install @vit-foundation/ui
 ```
 
-Requires `svelte` ^5.0.0 as a peer. Import the two stylesheets once:
+Requires `svelte` ^5.0.0 as a peer. `ScrollySteps`, alone in the package,
+also needs the optional peer `@sveltejs/svelte-scroller` — see
+[scrolly](./docs/components/scrolly.md#installing-the-peer). Import the two
+stylesheets once:
 
 ```svelte
 <script>
@@ -29,6 +32,8 @@ Everything exports flat from the root, and again grouped by role:
 | [`/chrome`](./docs/components/chrome.md)                        | PageShell, Nav, Footer                                                                                                                                                                                                                                                            |
 | [`/content`](./docs/components/content.md)                      | WeeklieCard, ProjectCard, Timeline, TimelineMilestone, TeamMemberCard, CollaboratorList, JobList, SortSelect, the nine page modules (HomePage … WeeklyPage) — plus the data shapes, the page-copy vocabulary, helpers and the two list rules (createWeeklyList, createUrlFilters) |
 | [`/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                                                                                           |
 | [`/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                                                                                                             |
@@ -50,7 +55,11 @@ integrates its i18n and router through one `UiProvider` in the root layout.
 - **Component reference** — [primitives](./docs/components/primitives.md) ·
   [chrome](./docs/components/chrome.md) ·
   [content](./docs/components/content.md) ·
-  [community](./docs/components/community.md)
+  [community](./docs/components/community.md) ·
+  [admin](./docs/components/admin.md) ·
+  [scrolly](./docs/components/scrolly.md)
+- **[Changelog](./docs/changelog/index.md)** — one page per version, newest
+  first; [unreleased](./docs/changelog/unreleased.md) is what is on `main`
 - **Storybook** — `npm run storybook`: every component has a story;
   `Edit mode/EditMode` demos the whole editing loop against an in-memory
   adapter
@@ -84,8 +93,43 @@ diffable against history. The public structure is the semantic entry points
 above, assembled in `src/lib/{primitives,chrome,content-components,community}.ts`
 and `src/lib/forms/index.ts`.
 
-Releases are MANUAL: bump with `npm version`, then `npm publish`. The
-workflow this paragraph used to describe fired on every `v*` tag, had no
-`NPM_TOKEN` and no lint, check or test step, so it failed every time and was
-deleted; `prepublishOnly` (lint, check, unit tests) is the only publish gate
-now. Push the tag by all means — nothing reads it.
+## Cutting a release
+
+Releases are MANUAL. The workflow this section used to describe fired on every
+`v*` tag, had no `NPM_TOKEN` and no lint, check or test step, so it failed
+every time and was deleted; `prepublishOnly` (lint, check, unit tests) is the
+only publish gate now.
+
+**While you work**, add the entry to
+[`docs/changelog/unreleased.md`](./docs/changelog/unreleased.md) in the same PR
+as the change, under one of Keep a Changelog's types — `Added`, `Changed`,
+`Deprecated`, `Removed`, `Fixed`, `Security` — or
+`Other (dependencies, CI, tools…)` for what a consumer never sees. One fact,
+one entry: if a type already covers the thing you changed, edit that entry so
+it describes the end state. A change a consumer must act on before upgrading
+carries an **Upgrading:** paragraph.
+
+**On release day**, in one commit (`chore(release): x.y.z`):
+
+1. Read `unreleased.md` once as a whole and merge what the individual PRs
+   restated.
+2. `git mv docs/changelog/unreleased.md docs/changelog/x.y.z.md`. Retitle it
+   `# x.y.z`, date it, and point its compare link at the tag range rather than
+   at `main`.
+3. Write a fresh `unreleased.md` with the same header and no entries — copy the
+   one you just renamed rather than inventing a new shape.
+4. Add the row to [`docs/changelog/index.md`](./docs/changelog/index.md).
+5. `npm version x.y.z` — MINOR for new exports and features, PATCH for fixes
+   alone, MAJOR for anything that breaks a consumer's imports or markup.
+6. `npm publish`. Check `npm view @vit-foundation/ui version` first: the
+   registry has been ahead of `main` before.
+7. `git push && git push origin vx.y.z`. Nothing automated reads the tag, but
+   the compare links in the changelog do.
+
+**Publish from a clean checkout of `main`, never from a tree with uncommitted
+work.** 0.28.0 was published from one: it carried an icon that reached npm and
+nothing else, and the next release would have silently removed it again if the
+tarball had not been diffed against the source first.
+
+A released page is history: never rewrite one to match later code. If it is
+wrong, say so on the next version's page.

package/dist/components/scrolly/CrossfadeVideo.svelte

@@ -0,0 +1,246 @@
+<!--
+	@component CrossfadeVideo
+
+	One responsive video: a desktop element and a mobile element, each with the
+	same three `<source>`s (webm → "safe" mp4 → mp4), plus the play / ended /
+	replay state that every scrolly video on the site used to re-implement.
+
+	Only one of the two elements is ever displayed (`desktopClass` /
+	`mobileClass` carry the breakpoint), but both exist so the browser picks the
+	right encode without a JS media query — the arrangement the feature
+	components already used.
+
+	Playback comes in two flavours:
+	- **managed** (default): the component plays from the first frame whenever
+	  `active` turns true and pauses when it turns false.
+	- **native** (`autoplay`): playback is the browser's, and `active` only
+	  matters for whatever classes the caller crossfades with.
+
+	Swapping the `<source>` children of a live `<video>` has no effect, so the
+	elements are keyed on their sources and recreated when those change.
+
+	@prop {string} [srcBase] - Folder the standard file names expand from:
+		`<srcBase>/desktop.webm`, `/desktop-safe.mp4`, `/desktop.mp4` and the
+		matching `mobile.*`. Ignored when `sources` is given.
+	@prop {CrossfadeVideoSources} [sources] - Explicit per-breakpoint sources,
+		for folders that don't follow the `desktop.*` / `mobile.*` naming.
+	@prop {boolean} [active=true] - Whether this video is the one on screen.
+		Drives managed playback.
+	@prop {boolean} [autoplay=false] - Hand playback to the browser (`autoplay`
+		on both elements) instead of managing it.
+	@prop {boolean} [loop=false] - Loop both elements.
+	@prop {string} [poster] - Poster frame for both elements.
+	@prop {string} [class] - Classes shared by both `<video>` elements.
+	@prop {string} [desktopClass='hidden lg:block'] - Extra classes on the
+		desktop element, carrying its breakpoint.
+	@prop {string} [mobileClass='block lg:hidden'] - Extra classes on the
+		mobile element, carrying its breakpoint.
+	@prop {boolean} [replayable=true] - Whether reaching the end offers a replay.
+	@prop {string} [replayClass] - Extra classes on the replay button, which is
+		already `absolute inset-0` over the caller's positioned wrapper.
+	@prop {string} [replayLabel='Replay video'] - Replay button aria-label.
+	@prop {Snippet} [overlay] - Replay button content. Defaults to the shared
+		reload badge.
+	@prop {() => void} [onended] - Called once when the video reaches its end.
+-->
+<script lang="ts" module>
+	/** The three encodes one breakpoint offers, in `<source>` order. */
+	export type CrossfadeVideoTrack = {
+		/** VP9/webm, preferred where it decodes. */
+		webm: string;
+		/** Conservatively encoded mp4, for players that choke on the main one. */
+		mp4Safe: string;
+		/** Main h.264 mp4. */
+		mp4: string;
+	};
+
+	/** Both breakpoints' encodes. */
+	export type CrossfadeVideoSources = {
+		desktop: CrossfadeVideoTrack;
+		mobile: CrossfadeVideoTrack;
+	};
+
+	/** What `bind:this` on a `<CrossfadeVideo>` exposes. */
+	export type CrossfadeVideoHandle = { replay: () => void };
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	let {
+		srcBase = '',
+		sources,
+		active = true,
+		autoplay = false,
+		loop = false,
+		poster,
+		class: className = '',
+		desktopClass = 'hidden lg:block',
+		mobileClass = 'block lg:hidden',
+		replayable = true,
+		replayClass = '',
+		replayLabel = 'Replay video',
+		overlay,
+		onended
+	}: {
+		srcBase?: string;
+		sources?: CrossfadeVideoSources;
+		active?: boolean;
+		autoplay?: boolean;
+		loop?: boolean;
+		poster?: string;
+		class?: string;
+		desktopClass?: string;
+		mobileClass?: string;
+		replayable?: boolean;
+		replayClass?: string;
+		replayLabel?: string;
+		overlay?: Snippet;
+		onended?: () => void;
+	} = $props();
+
+	const resolved: CrossfadeVideoSources = $derived(
+		sources ?? {
+			desktop: {
+				webm: `${srcBase}/desktop.webm`,
+				mp4Safe: `${srcBase}/desktop-safe.mp4`,
+				mp4: `${srcBase}/desktop.mp4`
+			},
+			mobile: {
+				webm: `${srcBase}/mobile.webm`,
+				mp4Safe: `${srcBase}/mobile-safe.mp4`,
+				mp4: `${srcBase}/mobile.mp4`
+			}
+		}
+	);
+
+	/** Recreating the elements is the only way a `<source>` swap takes effect. */
+	const srcKey = $derived(`${resolved.desktop.webm}|${resolved.mobile.webm}`);
+
+	let desktopEl = $state<HTMLVideoElement | null>(null);
+	let mobileEl = $state<HTMLVideoElement | null>(null);
+	let ended = $state(false);
+
+	/** Both elements, in the order they are played/paused. */
+	const elements = $derived([desktopEl, mobileEl]);
+
+	/** Rewinds and plays both elements. Autoplay rejections are expected. */
+	function playFromStart() {
+		ended = false;
+		for (const el of elements) {
+			if (!el) continue;
+			el.currentTime = 0;
+			// `play()` returns undefined in non-browser DOMs; normalize before catching
+			void Promise.resolve(el.play()).catch(() => {
+				// Autoplay may be blocked by the browser — silently fail
+			});
+		}
+	}
+
+	/**
+	 * Restarts playback from the first frame.
+	 *
+	 * Exposed on the component instance so a host that plays on its own trigger
+	 * (a section scrolling back into view, say) can ask for a replay.
+	 */
+	export function replay() {
+		playFromStart();
+	}
+
+	/** Leaves the video on its last frame and offers the replay affordance. */
+	function handleEnded() {
+		if (ended) return; // already handled by the other element
+		ended = true;
+		onended?.();
+	}
+
+	$effect(() => {
+		if (autoplay) return; // native playback: the browser owns it
+		if (active) playFromStart();
+		else for (const el of elements) el?.pause();
+	});
+</script>
+
+{#key srcKey}
+	<!-- Desktop -->
+	<video
+		bind:this={desktopEl}
+		muted
+		playsinline
+		{autoplay}
+		{loop}
+		{poster}
+		onended={handleEnded}
+		class="{className} {desktopClass}"
+	>
+		<source src={resolved.desktop.webm} type="video/webm" />
+		<source src={resolved.desktop.mp4Safe} type="video/mp4" />
+		<source src={resolved.desktop.mp4} type="video/mp4" />
+	</video>
+
+	<!-- Mobile -->
+	<video
+		bind:this={mobileEl}
+		muted
+		playsinline
+		{autoplay}
+		{loop}
+		{poster}
+		onended={handleEnded}
+		class="{className} {mobileClass}"
+	>
+		<source src={resolved.mobile.webm} type="video/webm" />
+		<source src={resolved.mobile.mp4Safe} type="video/mp4" />
+		<source src={resolved.mobile.mp4} type="video/mp4" />
+	</video>
+
+	{#if ended && replayable}
+		<button onclick={replay} class="vit-video__replay {replayClass}" aria-label={replayLabel}>
+			{#if overlay}
+				{@render overlay()}
+			{:else}
+				<!-- The default badge draws its own icon rather than fetching one:
+				     a package cannot assume a host ships `/common/reload.svg`. Pass
+				     the `overlay` snippet to replace it entirely. -->
+				<span class="vit-video__replay-badge">
+					<svg viewBox="0 0 24 24" width="28" height="28" aria-hidden="true" focusable="false">
+						<path d="M12 5V2L8 6l4 4V7a5 5 0 1 1-5 5H5a7 7 0 1 0 7-7Z" fill="currentColor" />
+					</svg>
+				</span>
+			{/if}
+		</button>
+	{/if}
+{/key}
+
+<style>
+	/*
+	 * The replay affordance covers the finished video. Presentation is plain CSS
+	 * so the component needs no framework; pass `replayClass` or the `overlay`
+	 * snippet to restyle it.
+	 */
+	.vit-video__replay {
+		position: absolute;
+		inset: 0;
+		z-index: 10;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: 0;
+		border: 0;
+		background: none;
+		cursor: pointer;
+		pointer-events: auto;
+	}
+
+	.vit-video__replay-badge {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		padding: var(--video-badge-padding, 1rem);
+		border-radius: 9999px;
+		color: var(--video-badge-color, #111827);
+		background: var(--video-badge-bg, rgb(255 255 255 / 0.5));
+		backdrop-filter: blur(4px);
+		-webkit-backdrop-filter: blur(4px);
+	}
+</style>

package/dist/components/scrolly/CrossfadeVideo.svelte.d.ts

@@ -0,0 +1,85 @@
+/** The three encodes one breakpoint offers, in `<source>` order. */
+export type CrossfadeVideoTrack = {
+    /** VP9/webm, preferred where it decodes. */
+    webm: string;
+    /** Conservatively encoded mp4, for players that choke on the main one. */
+    mp4Safe: string;
+    /** Main h.264 mp4. */
+    mp4: string;
+};
+/** Both breakpoints' encodes. */
+export type CrossfadeVideoSources = {
+    desktop: CrossfadeVideoTrack;
+    mobile: CrossfadeVideoTrack;
+};
+/** What `bind:this` on a `<CrossfadeVideo>` exposes. */
+export type CrossfadeVideoHandle = {
+    replay: () => void;
+};
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    srcBase?: string;
+    sources?: CrossfadeVideoSources;
+    active?: boolean;
+    autoplay?: boolean;
+    loop?: boolean;
+    poster?: string;
+    class?: string;
+    desktopClass?: string;
+    mobileClass?: string;
+    replayable?: boolean;
+    replayClass?: string;
+    replayLabel?: string;
+    overlay?: Snippet;
+    onended?: () => void;
+};
+/**
+ * CrossfadeVideo
+ *
+ * One responsive video: a desktop element and a mobile element, each with the
+ * same three `<source>`s (webm → "safe" mp4 → mp4), plus the play / ended /
+ * replay state that every scrolly video on the site used to re-implement.
+ *
+ * Only one of the two elements is ever displayed (`desktopClass` /
+ * `mobileClass` carry the breakpoint), but both exist so the browser picks the
+ * right encode without a JS media query — the arrangement the feature
+ * components already used.
+ *
+ * Playback comes in two flavours:
+ * - **managed** (default): the component plays from the first frame whenever
+ *   `active` turns true and pauses when it turns false.
+ * - **native** (`autoplay`): playback is the browser's, and `active` only
+ *   matters for whatever classes the caller crossfades with.
+ *
+ * Swapping the `<source>` children of a live `<video>` has no effect, so the
+ * elements are keyed on their sources and recreated when those change.
+ *
+ * @prop {string} [srcBase] - Folder the standard file names expand from:
+ * 	`<srcBase>/desktop.webm`, `/desktop-safe.mp4`, `/desktop.mp4` and the
+ * 	matching `mobile.*`. Ignored when `sources` is given.
+ * @prop {CrossfadeVideoSources} [sources] - Explicit per-breakpoint sources,
+ * 	for folders that don't follow the `desktop.*` / `mobile.*` naming.
+ * @prop {boolean} [active=true] - Whether this video is the one on screen.
+ * 	Drives managed playback.
+ * @prop {boolean} [autoplay=false] - Hand playback to the browser (`autoplay`
+ * 	on both elements) instead of managing it.
+ * @prop {boolean} [loop=false] - Loop both elements.
+ * @prop {string} [poster] - Poster frame for both elements.
+ * @prop {string} [class] - Classes shared by both `<video>` elements.
+ * @prop {string} [desktopClass='hidden lg:block'] - Extra classes on the
+ * 	desktop element, carrying its breakpoint.
+ * @prop {string} [mobileClass='block lg:hidden'] - Extra classes on the
+ * 	mobile element, carrying its breakpoint.
+ * @prop {boolean} [replayable=true] - Whether reaching the end offers a replay.
+ * @prop {string} [replayClass] - Extra classes on the replay button, which is
+ * 	already `absolute inset-0` over the caller's positioned wrapper.
+ * @prop {string} [replayLabel='Replay video'] - Replay button aria-label.
+ * @prop {Snippet} [overlay] - Replay button content. Defaults to the shared
+ * 	reload badge.
+ * @prop {() => void} [onended] - Called once when the video reaches its end.
+ */
+declare const CrossfadeVideo: import("svelte").Component<$$ComponentProps, {
+    replay: () => void;
+}, "">;
+type CrossfadeVideo = ReturnType<typeof CrossfadeVideo>;
+export default CrossfadeVideo;

package/dist/components/scrolly/GlassCard.svelte

@@ -0,0 +1,39 @@
+<!--
+  @component GlassCard
+
+  A frosted panel: padding plus a backdrop blur, and nothing else. It exists
+  because the same two declarations were being written at ten call sites.
+
+  | property             | default  |
+  |----------------------|----------|
+  | `--glass-padding`| `2.25rem`|
+  | `--glass-blur`   | `4px`    |
+
+  @prop {string} [class] - Extra classes appended to the panel
+  @prop {Snippet} children - The panel's contents
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	let {
+		class: className = '',
+		children,
+		...rest
+	}: {
+		class?: string;
+		children: Snippet;
+		[key: string]: unknown;
+	} = $props();
+</script>
+
+<div class="vit-glass {className}" {...rest}>
+	{@render children()}
+</div>
+
+<style>
+	.vit-glass {
+		padding: var(--glass-padding, 2.25rem);
+		backdrop-filter: blur(var(--glass-blur, 4px));
+		-webkit-backdrop-filter: blur(var(--glass-blur, 4px));
+	}
+</style>

package/dist/components/scrolly/GlassCard.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    class?: string;
+    children: Snippet;
+    [key: string]: unknown;
+};
+/**
+ * GlassCard
+ *
+ * A frosted panel: padding plus a backdrop blur, and nothing else. It exists
+ * because the same two declarations were being written at ten call sites.
+ *
+ * | property             | default  |
+ * |----------------------|----------|
+ * | `--glass-padding`| `2.25rem`|
+ * | `--glass-blur`   | `4px`    |
+ *
+ * @prop {string} [class] - Extra classes appended to the panel
+ * @prop {Snippet} children - The panel's contents
+ */
+declare const GlassCard: import("svelte").Component<$$ComponentProps, {}, "">;
+type GlassCard = ReturnType<typeof GlassCard>;
+export default GlassCard;

package/dist/components/scrolly/ScrollyStepIndicator.svelte

@@ -0,0 +1,93 @@
+<!--
+  @component ScrollyStepIndicator
+
+  The row (or column) of dots that shows which step of a scrolly a reader is on,
+  optionally clickable to jump.
+
+  Colours arrive as CSS custom properties rather than class-name props. The
+  version this was extracted from took `activeColor="bg-[#3E2A12] ring-1 …"` —
+  Tailwind class strings with a brand hex baked into the default — which meant a
+  consumer had to have Tailwind *and* had to restate the whole class list to
+  change one colour.
+
+  | property               | default   |
+  |------------------------|-----------|
+  | `--dot-size`       | `0.375rem`|
+  | `--dot-gap`        | `0.5rem`  |
+  | `--dot-color`      | `currentColor` |
+  | `--dot-active`     | `var(--dot-color, currentColor)` |
+
+  @prop {number} total - How many steps
+  @prop {number} current - Index of the active step
+  @prop {(index: number) => void} [onSelect] - Makes the dots buttons that jump
+  @prop {'vertical' | 'horizontal'} [orientation] - Layout direction
+  @prop {string} [class] - Extra classes appended to the container
+-->
+<script lang="ts">
+	let {
+		total,
+		current,
+		onSelect,
+		orientation = 'vertical',
+		class: className = ''
+	}: {
+		total: number;
+		current: number;
+		onSelect?: (index: number) => void;
+		orientation?: 'vertical' | 'horizontal';
+		class?: string;
+	} = $props();
+
+	const isHorizontal = $derived(orientation === 'horizontal');
+</script>
+
+<div class="vit-dots {className}" class:vit-dots--horizontal={isHorizontal}>
+	{#each Array.from({ length: total }, (_, k) => k) as i (i)}
+		{#if onSelect}
+			<button
+				type="button"
+				aria-label="Go to slide {i + 1}"
+				aria-current={i === current ? 'true' : undefined}
+				onclick={() => onSelect(i)}
+				class="vit-dots__dot vit-dots__dot--button"
+				class:vit-dots__dot--active={i === current}
+			></button>
+		{:else}
+			<div class="vit-dots__dot" class:vit-dots__dot--active={i === current}></div>
+		{/if}
+	{/each}
+</div>
+
+<style>
+	.vit-dots {
+		display: flex;
+		flex-direction: column;
+		gap: var(--dot-gap, 0.5rem);
+	}
+
+	.vit-dots--horizontal {
+		flex-direction: row;
+	}
+
+	.vit-dots__dot {
+		width: var(--dot-size, 0.375rem);
+		height: var(--dot-size, 0.375rem);
+		border-radius: 9999px;
+		background: transparent;
+		box-shadow: inset 0 0 0 1px var(--dot-color, currentColor);
+		transition:
+			background-color 300ms,
+			box-shadow 300ms;
+	}
+
+	.vit-dots__dot--active {
+		background: var(--dot-active, var(--dot-color, currentColor));
+	}
+
+	.vit-dots__dot--button {
+		padding: 0;
+		border: 0;
+		cursor: pointer;
+		appearance: none;
+	}
+</style>

package/dist/components/scrolly/ScrollyStepIndicator.svelte.d.ts

@@ -0,0 +1,35 @@
+type $$ComponentProps = {
+    total: number;
+    current: number;
+    onSelect?: (index: number) => void;
+    orientation?: 'vertical' | 'horizontal';
+    class?: string;
+};
+/**
+ * ScrollyStepIndicator
+ *
+ * The row (or column) of dots that shows which step of a scrolly a reader is on,
+ * optionally clickable to jump.
+ *
+ * Colours arrive as CSS custom properties rather than class-name props. The
+ * version this was extracted from took `activeColor="bg-[#3E2A12] ring-1 …"` —
+ * Tailwind class strings with a brand hex baked into the default — which meant a
+ * consumer had to have Tailwind *and* had to restate the whole class list to
+ * change one colour.
+ *
+ * | property               | default   |
+ * |------------------------|-----------|
+ * | `--dot-size`       | `0.375rem`|
+ * | `--dot-gap`        | `0.5rem`  |
+ * | `--dot-color`      | `currentColor` |
+ * | `--dot-active`     | `var(--dot-color, currentColor)` |
+ *
+ * @prop {number} total - How many steps
+ * @prop {number} current - Index of the active step
+ * @prop {(index: number) => void} [onSelect] - Makes the dots buttons that jump
+ * @prop {'vertical' | 'horizontal'} [orientation] - Layout direction
+ * @prop {string} [class] - Extra classes appended to the container
+ */
+declare const ScrollyStepIndicator: import("svelte").Component<$$ComponentProps, {}, "">;
+type ScrollyStepIndicator = ReturnType<typeof ScrollyStepIndicator>;
+export default ScrollyStepIndicator;

package/dist/components/scrolly/ScrollySteps.svelte

@@ -0,0 +1,112 @@
+<!--
+	@component ScrollySteps
+
+	The one scrolly mechanism: a sticky background with a column of scrolling
+	step sections over it.
+
+	Wraps `@sveltejs/svelte-scroller` (a Svelte 4 component, driven through its
+	legacy `background`/`foreground` slots) and owns everything every scrolly
+	section on the site used to re-implement by hand: the `index`/`offset`
+	state, the `<Scroller>` element, the `scrolly-bg` sticky wrapper, and the
+	per-step opacity/translateY ramp (see `./scrollySteps.ts`).
+
+	Content stays in the feature component: `background` paints whatever sits
+	behind, `step` paints one section's card. One `<section>` is rendered per
+	entry of `steps` — including spacer/buffer entries, since the scroller
+	counts `<section>` elements to decide `index`. Sections that are not steps
+	at all (a trailing "hold" section, say) go in `before`/`after`.
+
+	@prop {T[]} steps - One entry per `<section>`, in scroll order. Spacer
+		sections are entries too, so `index` lines up with the array.
+	@prop {number} [top=0] - Scroller `top`, as a fraction of the viewport.
+	@prop {number} [bottom=1] - Scroller `bottom`, as a fraction of the viewport.
+	@prop {number} [threshold=0.5] - Viewport fraction at which a section
+		becomes the current step.
+	@prop {number} [index=0] - Bindable. Step index the scroller reports.
+	@prop {number} [offset=0] - Bindable. Scroll progress within that step, 0 → 1.
+	@prop {Snippet} background - Sticky background, rendered inside the
+		`scrolly-bg` wrapper. Receives `{ index, offset, progress }`.
+	@prop {Snippet} step - One step's content, rendered inside its `<section>`.
+		Receives `{ item, i, active, opacity, translateY }`.
+	@prop {Snippet} [before] - Raw sections rendered before the step sections.
+	@prop {Snippet} [after] - Raw sections rendered after the step sections
+		(trailing buffer / hold sections).
+	@prop {string} [class='w-full'] - Classes on the foreground column.
+	@prop {string} [backgroundClass] - Extra classes next to `scrolly-bg`.
+	@prop {string | ((item: T, i: number) => string)} [sectionClass] - Classes
+		on each step `<section>`; a function when they differ per step.
+-->
+<script lang="ts" generics="T">
+	import type { Snippet } from 'svelte';
+	import Scroller from '@sveltejs/svelte-scroller';
+	import { stepStyle } from './stepStyle.js';
+
+	let {
+		steps,
+		top = 0,
+		bottom = 1,
+		threshold = 0.5,
+		index = $bindable(0),
+		offset = $bindable(0),
+		background,
+		step,
+		before,
+		after,
+		class: className = 'w-full',
+		backgroundClass = '',
+		sectionClass = ''
+	}: {
+		steps: T[];
+		top?: number;
+		bottom?: number;
+		threshold?: number;
+		index?: number;
+		offset?: number;
+		background: Snippet<[{ index: number; offset: number; progress: number }]>;
+		step: Snippet<[{ item: T; i: number; active: boolean; opacity: number; translateY: number }]>;
+		before?: Snippet;
+		after?: Snippet;
+		class?: string;
+		backgroundClass?: string;
+		sectionClass?: string | ((item: T, i: number) => string);
+	} = $props();
+
+	/** Scroller progress across the whole sequence, 0 → 1. Handed to `background`. */
+	let progress = $state(0);
+
+	/** Resolves the per-section class list, which may depend on the step. */
+	function classFor(item: T, i: number): string {
+		return typeof sectionClass === 'function' ? sectionClass(item, i) : sectionClass;
+	}
+</script>
+
+<Scroller {top} {bottom} {threshold} bind:index bind:offset bind:progress>
+	<!-- BACKGROUND: sticky, full viewport height -->
+	<div slot="background" class="vit-scrolly__bg {backgroundClass}">
+		{@render background({ index, offset, progress })}
+	</div>
+
+	<!-- FOREGROUND: the step sections, scrolling over the background -->
+	<div slot="foreground" class={className}>
+		{@render before?.()}
+		{#each steps as item, i (i)}
+			<section class={classFor(item, i)}>
+				{@render step({ item, i, ...stepStyle(i, index, offset) })}
+			</section>
+		{/each}
+		{@render after?.()}
+	</div>
+</Scroller>
+
+<style>
+	/*
+	 * The sticky background fills the viewport. `--device-h` lets a host pin a
+	 * measured height instead of `100vh`, which is what mobile browsers need
+	 * when the URL bar collapses and `vh` jumps.
+	 */
+	.vit-scrolly__bg {
+		position: relative;
+		width: 100%;
+		height: var(--device-h, 100vh);
+	}
+</style>

package/dist/components/scrolly/ScrollySteps.svelte.d.ts

@@ -0,0 +1,87 @@
+import type { Snippet } from 'svelte';
+declare function $$render<T>(): {
+    props: {
+        steps: T[];
+        top?: number;
+        bottom?: number;
+        threshold?: number;
+        index?: number;
+        offset?: number;
+        background: Snippet<[{
+            index: number;
+            offset: number;
+            progress: number;
+        }]>;
+        step: Snippet<[{
+            item: T;
+            i: number;
+            active: boolean;
+            opacity: number;
+            translateY: number;
+        }]>;
+        before?: Snippet;
+        after?: Snippet;
+        class?: string;
+        backgroundClass?: string;
+        sectionClass?: string | ((item: T, i: number) => string);
+    };
+    exports: {};
+    bindings: "index" | "offset";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "index" | "offset";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * ScrollySteps
+ *
+ * The one scrolly mechanism: a sticky background with a column of scrolling
+ * step sections over it.
+ *
+ * Wraps `@sveltejs/svelte-scroller` (a Svelte 4 component, driven through its
+ * legacy `background`/`foreground` slots) and owns everything every scrolly
+ * section on the site used to re-implement by hand: the `index`/`offset`
+ * state, the `<Scroller>` element, the `scrolly-bg` sticky wrapper, and the
+ * per-step opacity/translateY ramp (see `./scrollySteps.ts`).
+ *
+ * Content stays in the feature component: `background` paints whatever sits
+ * behind, `step` paints one section's card. One `<section>` is rendered per
+ * entry of `steps` — including spacer/buffer entries, since the scroller
+ * counts `<section>` elements to decide `index`. Sections that are not steps
+ * at all (a trailing "hold" section, say) go in `before`/`after`.
+ *
+ * @prop {T[]} steps - One entry per `<section>`, in scroll order. Spacer
+ * 	sections are entries too, so `index` lines up with the array.
+ * @prop {number} [top=0] - Scroller `top`, as a fraction of the viewport.
+ * @prop {number} [bottom=1] - Scroller `bottom`, as a fraction of the viewport.
+ * @prop {number} [threshold=0.5] - Viewport fraction at which a section
+ * 	becomes the current step.
+ * @prop {number} [index=0] - Bindable. Step index the scroller reports.
+ * @prop {number} [offset=0] - Bindable. Scroll progress within that step, 0 → 1.
+ * @prop {Snippet} background - Sticky background, rendered inside the
+ * 	`scrolly-bg` wrapper. Receives `{ index, offset, progress }`.
+ * @prop {Snippet} step - One step's content, rendered inside its `<section>`.
+ * 	Receives `{ item, i, active, opacity, translateY }`.
+ * @prop {Snippet} [before] - Raw sections rendered before the step sections.
+ * @prop {Snippet} [after] - Raw sections rendered after the step sections
+ * 	(trailing buffer / hold sections).
+ * @prop {string} [class='w-full'] - Classes on the foreground column.
+ * @prop {string} [backgroundClass] - Extra classes next to `scrolly-bg`.
+ * @prop {string | ((item: T, i: number) => string)} [sectionClass] - Classes
+ * 	on each step `<section>`; a function when they differ per step.
+ */
+declare const ScrollySteps: $$IsomorphicComponent;
+type ScrollySteps<T> = InstanceType<typeof ScrollySteps<T>>;
+export default ScrollySteps;

package/dist/components/scrolly/stepStyle.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module scrolly/stepStyle
+ *
+ * The per-step style a scrolly card is drawn with, derived from the scroller's
+ * `index` / `offset` pair. No DOM, no Svelte — the ramp is assertable as
+ * numbers, which is the whole reason it is not inline in the component.
+ *
+ * In the app this came from, the same arithmetic lived in two modules:
+ * `scrollyUtils.ts` held `calcOpacity` / `calcTranslateY`, and a six-line
+ * `scrollySteps.ts` re-exported them zipped into one record. Two modules for one
+ * three-field value is a pass-through, not a seam, so they are one module here.
+ * Both halves stay exported: a caller that wants only the opacity ramp should
+ * not have to take the record.
+ */
+/** Everything one step needs to draw itself for the current scroll position. */
+export type StepStyle = {
+    /** True when this step is the one the scroller currently reports. */
+    active: boolean;
+    /** Card opacity: 0 → 1 → 1 → 0 across the step's own scroll progress. */
+    opacity: number;
+    /** Card translateY in px: 30 → 0 → 0 → -30 across that same progress. */
+    translateY: number;
+};
+/**
+ * Card opacity across a step's scroll progress: fade in over the first quarter,
+ * hold through the middle half, fade out over the last quarter.
+ *
+ * @param stepIndex - Index of the step being drawn.
+ * @param currentIndex - Step index the scroller currently reports.
+ * @param currentOffset - Scroll progress within the current step, 0 → 1.
+ * @returns Opacity in `[0, 1]`; `0` for any step that is not current.
+ */
+export declare function calcOpacity(stepIndex: number, currentIndex: number, currentOffset: number): number;
+/**
+ * Card translateY in px across the same progress: slides up on entry, holds
+ * through the plateau, slides further up on exit.
+ *
+ * @param stepIndex - Index of the step being drawn.
+ * @param currentIndex - Step index the scroller currently reports.
+ * @param currentOffset - Scroll progress within the current step, 0 → 1.
+ * @returns Offset in px; the full travel for any step that is not current, so
+ *   an inactive card is parked below rather than mid-animation.
+ */
+export declare function calcTranslateY(stepIndex: number, currentIndex: number, currentOffset: number): number;
+/**
+ * Projects the scroller's position onto one step.
+ *
+ * @param i - Index of the step being drawn.
+ * @param index - Step index the scroller currently reports.
+ * @param offset - Scroll progress within the current step, 0 → 1.
+ * @returns The step's `active` flag plus its card opacity and translateY.
+ */
+export declare function stepStyle(i: number, index: number, offset: number): StepStyle;

package/dist/components/scrolly/stepStyle.js

@@ -0,0 +1,64 @@
+/**
+ * @module scrolly/stepStyle
+ *
+ * The per-step style a scrolly card is drawn with, derived from the scroller's
+ * `index` / `offset` pair. No DOM, no Svelte — the ramp is assertable as
+ * numbers, which is the whole reason it is not inline in the component.
+ *
+ * In the app this came from, the same arithmetic lived in two modules:
+ * `scrollyUtils.ts` held `calcOpacity` / `calcTranslateY`, and a six-line
+ * `scrollySteps.ts` re-exported them zipped into one record. Two modules for one
+ * three-field value is a pass-through, not a seam, so they are one module here.
+ * Both halves stay exported: a caller that wants only the opacity ramp should
+ * not have to take the record.
+ */
+/** How far the card slides, in px, at the extremes of a step. */
+const TRAVEL_PX = 30;
+/**
+ * Card opacity across a step's scroll progress: fade in over the first quarter,
+ * hold through the middle half, fade out over the last quarter.
+ *
+ * @param stepIndex - Index of the step being drawn.
+ * @param currentIndex - Step index the scroller currently reports.
+ * @param currentOffset - Scroll progress within the current step, 0 → 1.
+ * @returns Opacity in `[0, 1]`; `0` for any step that is not current.
+ */
+export function calcOpacity(stepIndex, currentIndex, currentOffset) {
+    if (stepIndex !== currentIndex)
+        return 0;
+    return Math.max(0, Math.min(currentOffset * 4, 1, (1 - currentOffset) * 4));
+}
+/**
+ * Card translateY in px across the same progress: slides up on entry, holds
+ * through the plateau, slides further up on exit.
+ *
+ * @param stepIndex - Index of the step being drawn.
+ * @param currentIndex - Step index the scroller currently reports.
+ * @param currentOffset - Scroll progress within the current step, 0 → 1.
+ * @returns Offset in px; the full travel for any step that is not current, so
+ *   an inactive card is parked below rather than mid-animation.
+ */
+export function calcTranslateY(stepIndex, currentIndex, currentOffset) {
+    if (stepIndex !== currentIndex)
+        return TRAVEL_PX;
+    if (currentOffset < 0.25)
+        return (1 - currentOffset * 4) * TRAVEL_PX;
+    if (currentOffset < 0.75)
+        return 0;
+    return -(currentOffset - 0.75) * 4 * TRAVEL_PX;
+}
+/**
+ * Projects the scroller's position onto one step.
+ *
+ * @param i - Index of the step being drawn.
+ * @param index - Step index the scroller currently reports.
+ * @param offset - Scroll progress within the current step, 0 → 1.
+ * @returns The step's `active` flag plus its card opacity and translateY.
+ */
+export function stepStyle(i, index, offset) {
+    return {
+        active: i === index,
+        opacity: calcOpacity(i, index, offset),
+        translateY: calcTranslateY(i, index, offset)
+    };
+}

package/dist/components/scrolly/svelte-scroller.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@sveltejs/svelte-scroller` ships no type declarations, so the peer it is
+ * declared as is untyped without this. It lives under `src/lib` deliberately:
+ * `svelte-package` emits it into `dist`, so a consumer of this package inherits
+ * the declaration instead of having to write their own — which is what the app
+ * this was extracted from had to do.
+ */
+declare module '@sveltejs/svelte-scroller' {
+	import type { SvelteComponent } from 'svelte';
+
+	export default class Scroller extends SvelteComponent<{
+		top?: number;
+		bottom?: number;
+		threshold?: number;
+		query?: string;
+		parallax?: boolean;
+		index?: number;
+		count?: number;
+		offset?: number;
+		progress?: number;
+		visible?: boolean;
+	}> {}
+}

package/dist/scrolly.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Scrollytelling primitives: the scroller and its step ramp, a responsive
+ * crossfading video, step dots, and a frosted panel. Domain-free, and themed
+ * with CSS custom properties rather than utility classes.
+ *
+ * `<ScrollySteps>` needs the optional peer `@sveltejs/svelte-scroller`; nothing
+ * else here does, so a consumer that only wants `CrossfadeVideo` or the
+ * `stepStyle` ramp can skip it.
+ */
+export { default as ScrollySteps } from './components/scrolly/ScrollySteps.svelte';
+export { default as ScrollyStepIndicator } from './components/scrolly/ScrollyStepIndicator.svelte';
+export { default as CrossfadeVideo } from './components/scrolly/CrossfadeVideo.svelte';
+export type { CrossfadeVideoHandle } from './components/scrolly/CrossfadeVideo.svelte';
+export { default as GlassCard } from './components/scrolly/GlassCard.svelte';
+export { calcOpacity, calcTranslateY, stepStyle, type StepStyle } from './components/scrolly/stepStyle.js';

package/dist/scrolly.js

@@ -0,0 +1,14 @@
+/**
+ * Scrollytelling primitives: the scroller and its step ramp, a responsive
+ * crossfading video, step dots, and a frosted panel. Domain-free, and themed
+ * with CSS custom properties rather than utility classes.
+ *
+ * `<ScrollySteps>` needs the optional peer `@sveltejs/svelte-scroller`; nothing
+ * else here does, so a consumer that only wants `CrossfadeVideo` or the
+ * `stepStyle` ramp can skip it.
+ */
+export { default as ScrollySteps } from './components/scrolly/ScrollySteps.svelte';
+export { default as ScrollyStepIndicator } from './components/scrolly/ScrollyStepIndicator.svelte';
+export { default as CrossfadeVideo } from './components/scrolly/CrossfadeVideo.svelte';
+export { default as GlassCard } from './components/scrolly/GlassCard.svelte';
+export { calcOpacity, calcTranslateY, stepStyle } from './components/scrolly/stepStyle.js';

package/dist/styles/tokens.css

@@ -65,4 +65,18 @@
 
 	/* Motion */
 	--transition-fast: 150ms ease;
+
+	/* Scrollytelling (the `./scrolly` subpath) */
+	/* The sticky background's height. Mobile browsers change `100vh` when the
+	   URL bar collapses, so a host that measures the real viewport sets this. */
+	--device-h: 100vh;
+	--dot-size: 0.375rem;
+	--dot-gap: var(--space-2);
+	--dot-color: currentColor;
+	--dot-active: var(--dot-color);
+	--glass-padding: var(--space-5);
+	--glass-blur: 4px;
+	--video-badge-padding: var(--space-3);
+	--video-badge-color: var(--color-ink);
+	--video-badge-bg: rgb(255 255 255 / 50%);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vit-foundation/ui",
-	"version": "0.28.0",
+	"version": "0.30.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -91,10 +91,16 @@
 			"default": "./dist/testing/remote-form.js"
 		},
 		"./tokens.css": "./dist/styles/tokens.css",
-		"./base.css": "./dist/styles/base.css"
+		"./base.css": "./dist/styles/base.css",
+		"./scrolly": {
+			"types": "./dist/scrolly.d.ts",
+			"svelte": "./dist/scrolly.js",
+			"default": "./dist/scrolly.js"
+		}
 	},
 	"peerDependencies": {
-		"svelte": "^5.0.0"
+		"svelte": "^5.0.0",
+		"@sveltejs/svelte-scroller": "^2.0.0"
 	},
 	"devDependencies": {
 		"@chromatic-com/storybook": "^4.1.2",
@@ -109,6 +115,7 @@
 		"@sveltejs/adapter-auto": "^7.0.0",
 		"@sveltejs/kit": "^2.47.1",
 		"@sveltejs/package": "^2.5.4",
+		"@sveltejs/svelte-scroller": "^2.0.7",
 		"@sveltejs/vite-plugin-svelte": "^6.2.1",
 		"@types/node": "^22",
 		"@vitest/browser-playwright": "^4.0.5",
@@ -142,5 +149,10 @@
 	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"peerDependenciesMeta": {
+		"@sveltejs/svelte-scroller": {
+			"optional": true
+		}
 	}
 }