@vit-foundation/ui 0.29.0 → 0.31.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/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/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/scrolly.d.ts

@@ -10,5 +10,6 @@
 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/styles/tokens.css

@@ -79,4 +79,17 @@
 	--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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vit-foundation/ui",
-	"version": "0.29.0",
+	"version": "0.31.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -96,6 +96,11 @@
 			"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"
 		}
 	},
 	"peerDependencies": {