@vit-foundation/ui 0.22.0 → 0.24.0

package/dist/admin.d.ts

@@ -5,7 +5,6 @@
  * components receive already-filtered data through props, the Nav/Footer
  * genericization pattern.
  */
-export { default as AdminShell } from './components/admin/AdminShell.svelte';
 export { default as DecorMosaic } from './components/admin/DecorMosaic.svelte';
 export { default as PageHeading } from './components/admin/PageHeading.svelte';
 export { default as Sidebar, type SidebarItem } from './components/admin/Sidebar.svelte';

package/dist/admin.js

@@ -5,7 +5,15 @@
  * components receive already-filtered data through props, the Nav/Footer
  * genericization pattern.
  */
-export { default as AdminShell } from './components/admin/AdminShell.svelte';
+/*
+ * `AdminShell` was exported here — a public name behind two doors with zero
+ * readers in either host, no test, and one story. Seven props, five of them
+ * forwarded verbatim to `Sidebar`, and the only implementation it added beyond
+ * the forwarding was `main { margin-left: 4.5rem }`. The one admin host went
+ * the other way: vit-brain imports `Sidebar` directly and composes its own
+ * shell with a different offset, so the rail's width had two answers and the
+ * untested one was nobody's. Deleting it left nothing to reappear.
+ */
 export { default as DecorMosaic } from './components/admin/DecorMosaic.svelte';
 export { default as PageHeading } from './components/admin/PageHeading.svelte';
 export { default as Sidebar } from './components/admin/Sidebar.svelte';

package/dist/components/admin/Sidebar.svelte

@@ -95,7 +95,15 @@
 		box-shadow: var(--shadow-1);
 	}
 
-	.item {
+	/*
+	 * The rail's footprint, and the host's footer control with it — "should sit
+	 * like an item" was the comment on a second, identical copy of these eleven
+	 * declarations, and vit-brain had a third on its own logout button. One
+	 * selector list is the whole rule: a host's footer submit is an item that
+	 * happens to come from outside.
+	 */
+	.item,
+	.footer :global(button) {
 		display: inline-flex;
 		align-items: center;
 		justify-content: center;
@@ -109,7 +117,8 @@
 		transition: background var(--transition-fast);
 	}
 
-	.item:hover {
+	.item:hover,
+	.footer :global(button:hover) {
 		background: color-mix(in srgb, var(--color-navy) 10%, transparent);
 	}
 
@@ -122,25 +131,6 @@
 		margin-top: auto;
 	}
 
-	/* The host's footer control (a logout submit) should sit like an item. */
-	.footer :global(button) {
-		display: inline-flex;
-		align-items: center;
-		justify-content: center;
-		width: 2.4rem;
-		height: 2.4rem;
-		border-radius: 999px;
-		color: var(--color-navy);
-		border: none;
-		background: transparent;
-		cursor: pointer;
-		transition: background var(--transition-fast);
-	}
-
-	.footer :global(button:hover) {
-		background: color-mix(in srgb, var(--color-navy) 10%, transparent);
-	}
-
 	@media print {
 		.sidebar {
 			display: none;

package/dist/components/layout/PageShell.svelte

@@ -1,12 +1,13 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import { getUiConfig } from '../../config/context.js';
+	import { documentTitle } from '../../utils/document-title.js';
 
 	/**
 	 * The chrome every page shares: the content column, the vertical rhythm,
-	 * and the browser title, composed as `title — siteName` from the config's
-	 * site name. (The foundation site's error page spells the same format on
-	 * its own; the two are one decision, noted in both places.)
+	 * and the browser title. The title FORMAT is `documentTitle`'s — the
+	 * foundation site's error page cannot render through this component and
+	 * needs the same format, and the two used to spell it separately.
 	 *
 	 * The shape is one named variant rather than four presentation flags.
 	 * Width, spacing, stacking and the wrapper element were independent props,
@@ -45,7 +46,7 @@
 	let { title, description, variant = 'content', children }: Props = $props();
 
 	const config = getUiConfig();
-	const pageTitle = $derived(title ? `${title} — ${config.siteName}` : config.siteName);
+	const pageTitle = $derived(documentTitle(title, config.siteName));
 	/**
 	 * The editorial variants render an <article>, and say so to crawlers too.
 	 * og:type was hardcoded to 'website' while the element already switched,

package/dist/components/layout/PageShell.svelte.d.ts

@@ -1,9 +1,9 @@
 import type { Snippet } from 'svelte';
 /**
  * The chrome every page shares: the content column, the vertical rhythm,
- * and the browser title, composed as `title — siteName` from the config's
- * site name. (The foundation site's error page spells the same format on
- * its own; the two are one decision, noted in both places.)
+ * and the browser title. The title FORMAT is `documentTitle`'s — the
+ * foundation site's error page cannot render through this component and
+ * needs the same format, and the two used to spell it separately.
  *
  * The shape is one named variant rather than four presentation flags.
  * Width, spacing, stacking and the wrapper element were independent props,

package/dist/content/index.d.ts

@@ -1,4 +1,4 @@
 export { renderBody } from './richtext.js';
 export type { RichTextBlock } from './richtext.js';
-export { CONTACT_CATEGORIES, MILESTONE_CATEGORIES, PROJECT_KINDS, REACTIONS } from './types.js';
-export type { CollaboratorData, CommentData, CommentThreadData, ContactCategory, FieldConstraint, FormFailReason, JobOpeningData, MilestoneCategory, MilestoneData, ProjectCardData, ProjectKind, Reaction, ReactionSummary, ReactionTarget, SortDirection, TeamMemberData, WeeklyCardData } from './types.js';
+export { COMMENT_STATUSES, CONTACT_CATEGORIES, MILESTONE_CATEGORIES, PROJECT_KINDS, REACTIONS } from './types.js';
+export type { CollaboratorData, CommentData, CommentThreadData, CommentStatus, ContactCategory, FieldConstraint, FormFailReason, JobOpeningData, MilestoneCategory, MilestoneData, ProjectCardData, ProjectKind, Reaction, ReactionSummary, ReactionTarget, SortDirection, TeamMemberData, WeeklyCardData } from './types.js';

package/dist/content/index.js

@@ -1,2 +1,2 @@
 export { renderBody } from './richtext.js';
-export { CONTACT_CATEGORIES, MILESTONE_CATEGORIES, PROJECT_KINDS, REACTIONS } from './types.js';
+export { COMMENT_STATUSES, CONTACT_CATEGORIES, MILESTONE_CATEGORIES, PROJECT_KINDS, REACTIONS } from './types.js';

package/dist/content/types.d.ts

@@ -126,6 +126,22 @@ export interface CommentData {
     createdAt: string;
     reactions: ReactionSummary[];
 }
+/**
+ * A comment's moderation state, as the database constrains it.
+ *
+ * The set is `comments.status`'s CHECK in fndvit-website and the vocabulary
+ * vit-brain's Comentaris tab moderates through — two repositories that cannot
+ * import each other — and it had no owner in TypeScript at all: the site read
+ * `status = 'published'` as a bare SQL literal in four queries, typed the
+ * field `z.string()`, and never named the other two states anywhere. A test
+ * fixture using `'visible'`, a value the CHECK refuses, passed green.
+ *
+ * `published` is what a reader sees; `hidden` is moderated away; `pending`
+ * awaits review. Which of them a given surface SHOWS is that surface's rule,
+ * not this list's.
+ */
+export declare const COMMENT_STATUSES: readonly ["published", "pending", "hidden"];
+export type CommentStatus = (typeof COMMENT_STATUSES)[number];
 /** A top-level comment with its flat reply list. */
 export interface CommentThreadData extends CommentData {
     replies: CommentData[];

package/dist/content/types.js

@@ -29,5 +29,20 @@ export const MILESTONE_CATEGORIES = [
 ];
 /** The reactions a weekly or comment can carry, in display order. */
 export const REACTIONS = ['like', 'love', 'clap'];
+/**
+ * A comment's moderation state, as the database constrains it.
+ *
+ * The set is `comments.status`'s CHECK in fndvit-website and the vocabulary
+ * vit-brain's Comentaris tab moderates through — two repositories that cannot
+ * import each other — and it had no owner in TypeScript at all: the site read
+ * `status = 'published'` as a bare SQL literal in four queries, typed the
+ * field `z.string()`, and never named the other two states anywhere. A test
+ * fixture using `'visible'`, a value the CHECK refuses, passed green.
+ *
+ * `published` is what a reader sees; `hidden` is moderated away; `pending`
+ * awaits review. Which of them a given surface SHOWS is that surface's rule,
+ * not this list's.
+ */
+export const COMMENT_STATUSES = ['published', 'pending', 'hidden'];
 /** The contact form's reasons, in display order — the host schema derives its enum from this. */
 export const CONTACT_CATEGORIES = ['collaborate', 'event', 'press', 'brand', 'other'];

package/dist/content-components.d.ts

@@ -23,7 +23,7 @@ export { createUrlFilters } from './utils/url-filters.svelte.js';
 export type { UrlFilters, UrlFiltersConfig } from './utils/url-filters.svelte.js';
 export { createWeeklyList } from './utils/weekly-list.svelte.js';
 export type { WeeklyList, WeeklyListConfig } from './utils/weekly-list.svelte.js';
-export { WEEKLY_LIST_DEFAULTS } from './utils/weekly-list-contract.js';
+export { WEEKLY_LIST_DEFAULTS, WEEKLY_LIST_PARAMS, parseWeeklyListUrl } from './utils/weekly-list-contract.js';
 export type { WeeklyListFilters, WeeklyListPage, WeeklyListServerData } from './utils/weekly-list-contract.js';
 export { contactCategoryLabel } from './utils/contact.js';
 export { formatDate, yearOf } from './utils/dates.js';

package/dist/content-components.js

@@ -18,6 +18,6 @@ export { createUrlFilters } from './utils/url-filters.svelte.js';
 export { createWeeklyList } from './utils/weekly-list.svelte.js';
 // The list's contract is component-free on purpose, so ./contract carries it
 // too — a host's +page.server.ts reads these without loading the grid.
-export { WEEKLY_LIST_DEFAULTS } from './utils/weekly-list-contract.js';
+export { WEEKLY_LIST_DEFAULTS, WEEKLY_LIST_PARAMS, parseWeeklyListUrl } from './utils/weekly-list-contract.js';
 export { contactCategoryLabel } from './utils/contact.js';
 export { formatDate, yearOf } from './utils/dates.js';

package/dist/contract.d.ts

@@ -45,14 +45,20 @@ export { REACTIONS } from './content/types.js';
 export type { Reaction, ReactionSummary, SortDirection } from './content/types.js';
 export { MILESTONE_CATEGORIES, PROJECT_KINDS } from './content/types.js';
 export type { MilestoneCategory, ProjectKind } from './content/types.js';
-export { WEEKLY_LIST_DEFAULTS } from './utils/weekly-list-contract.js';
+export { WEEKLY_LIST_DEFAULTS, WEEKLY_LIST_PARAMS, parseWeeklyListUrl } from './utils/weekly-list-contract.js';
 export type { WeeklyListFilters, WeeklyListPage, WeeklyListServerData } from './utils/weekly-list-contract.js';
 export { CONTACT_CATEGORIES } from './content/types.js';
-export type { ContactCategory, FieldConstraint, FormFailReason } from './content/types.js';
+export { COMMENT_STATUSES } from './content/types.js';
+export type { CommentStatus, ContactCategory, FieldConstraint, FormFailReason } from './content/types.js';
 export { COMMENT_BODY, CONTACT_MESSAGE, CONTACT_NAME, DISPLAY_NAME, EMAIL, LOGIN_PASSWORD, PASSWORD } from './forms/constraints.js';
 export { hasNewsletterIntent, HONEYPOT_FIELD, isNewsletterIntent, NEWSLETTER_INTENT_PARAM, NEWSLETTER_INTENT_VALUE, withNewsletterIntent } from './forms/transport.js';
 export type { FormFail, FormFieldIssue, FormResultLike, FormResultOf, KeyedRemoteForms, RemoteField, RemoteFormAttributes, RemoteFormInstance } from './forms/types.js';
-export { buildQueryString, isExternalUrl, isInternalPath, isPathUnder } from './utils/paths.js';
+export { buildQueryString, isExternalUrl, isInternalPath } from './utils/paths.js';
+/**
+ * The browser-title format. On `./contract` because its second reader is a
+ * host's error page, which composes a title without rendering `PageShell`.
+ */
+export { documentTitle } from './utils/document-title.js';
 /**
  * The descriptor factories. `edit/helpers.ts` imports nothing but types from
  * two modules this subpath already anchors, so it needed a door rather than a

package/dist/contract.js

@@ -44,11 +44,24 @@ export { REACTIONS } from './content/types.js';
 // contact form already derives from CONTACT_CATEGORIES below. Values, because
 // a type cannot be the source of an enum.
 export { MILESTONE_CATEGORIES, PROJECT_KINDS } from './content/types.js';
-export { WEEKLY_LIST_DEFAULTS } from './utils/weekly-list-contract.js';
+// The weeklies URL contract, both halves: the values a param stands for when
+// absent, the names it travels as, and the parse that reads one back. The read
+// half had three spellings across two repositories and this package's own test,
+// and the round-trip case guarding them crossed against the test's copy.
+export { WEEKLY_LIST_DEFAULTS, WEEKLY_LIST_PARAMS, parseWeeklyListUrl } from './utils/weekly-list-contract.js';
 export { CONTACT_CATEGORIES } from './content/types.js';
+export { COMMENT_STATUSES } from './content/types.js';
 export { COMMENT_BODY, CONTACT_MESSAGE, CONTACT_NAME, DISPLAY_NAME, EMAIL, LOGIN_PASSWORD, PASSWORD } from './forms/constraints.js';
 export { hasNewsletterIntent, HONEYPOT_FIELD, isNewsletterIntent, NEWSLETTER_INTENT_PARAM, NEWSLETTER_INTENT_VALUE, withNewsletterIntent } from './forms/transport.js';
-export { buildQueryString, isExternalUrl, isInternalPath, isPathUnder } from './utils/paths.js';
+// `isPathUnder` is deliberately absent: `Nav` and `Sidebar` reach it by relative
+// import and no host has ever imported it, so exporting it pinned a prefix rule
+// into semver for nobody. See utils/paths.ts.
+export { buildQueryString, isExternalUrl, isInternalPath } from './utils/paths.js';
+/**
+ * The browser-title format. On `./contract` because its second reader is a
+ * host's error page, which composes a title without rendering `PageShell`.
+ */
+export { documentTitle } from './utils/document-title.js';
 /**
  * The descriptor factories. `edit/helpers.ts` imports nothing but types from
  * two modules this subpath already anchors, so it needed a door rather than a

package/dist/index.js

@@ -12,13 +12,7 @@ export * from './forms/index.js';
 // App wiring: configuration context and the edit-mode contract.
 export * from './config/index.js';
 export * from './edit/index.js';
-// The one path utility a host actually reads: fndvit-website re-exports
-// `buildQueryString` from its own `utils/nav.ts`, so the URL a list mirrors
-// and the hrefs it renders are spelled by this function in both codebases.
-// The other three are NOT exported. `isInternalPath` and `isExternalUrl` are
-// the destination classifiers `Link` and `TimelineMilestone` branch on, and
-// `isPathUnder` is the prefix match `Nav` and `Sidebar` highlight the current
-// section with — all four in-package readers reach them by deep import, and
-// no host imports any of the three. Exporting them would pin their behaviour
-// into semver for no reader; `paths.test.ts` is what holds them instead.
+// The one path utility this BARREL carries. The destination classifiers are
+// 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';

package/dist/testing/imports.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What a source scan needs to see, and the anchors that keep it honest.
+ *
+ * Two guards in this package walk the source: `contract.test.ts` follows the
+ * relative import graph beneath `./contract`, and `no-app-imports.test.ts`
+ * scans every module for an app virtual specifier. They ask different
+ * questions of the same rule — WHICH MODULES DOES THIS ONE NAME — and each
+ * used to answer it with a pattern of its own. `contract.test.ts` found the
+ * defect in its copy and fixed it there:
+ *
+ *     "THREE import forms, because two of them used to be invisible here. The
+ *     pattern required the `from` keyword, so a side-effect import and a
+ *     dynamic one both walked past a guard whose whole job is to see them."
+ *
+ * The other copy was not fixed and still required `from`, so a dynamic import
+ * of an $app specifier walked past the gate that decides whether this package
+ * is publishable. Copying the lesson a third time is how a guard
+ * starts missing things again; the grammar lives here instead, and each guard
+ * filters the specifiers it cares about.
+ */
+/**
+ * Every module specifier a source file names, in all three forms a bundler
+ * follows: `from '…'` (import and re-export alike), a bare side-effect
+ * `import '…'`, and a dynamic `import('…')`.
+ *
+ * A type-only import is reported like any other. That is deliberate, and it
+ * is `contract.test.ts`'s standing argument: erasure is a build-time fact, and
+ * a pattern that has to understand `import type` is a pattern with a second
+ * way to be wrong.
+ */
+export declare function importSpecifiers(source: string): readonly string[];
+/**
+ * Every `.ts` and `.svelte` file beneath `root`, and the ones the walk MUST
+ * find.
+ *
+ * `mustReach` is a required argument for the reason `contract.test.ts` gives
+ * at length: an assertion over an empty list passes. `expect(offenders)
+ * .toEqual([])` is a clean bill of health over a walk that enumerated nothing
+ * — a directory renamed, a `readdirSync` that threw and was caught upstream,
+ * an entry filter that stopped matching — and a safety net that can narrow in
+ * silence reproduces the defect it exists to prevent. fndvit-website's
+ * `src/lib/testing/source-scan.ts` settled the shape: a scan cannot walk the
+ * tree without saying what it must find.
+ *
+ * Anchors are relative to `root` with `/` separators, so one representation
+ * crosses this interface and an anchor cannot silently fail to match an
+ * absolute path. A FLOOR was the alternative and is the thing being replaced:
+ * a walk that quietly stopped seeing two thirds of the tree clears any floor
+ * worth setting.
+ */
+export declare function sourceFiles(root: string, mustReach: readonly string[]): readonly string[];

package/dist/testing/imports.js

@@ -0,0 +1,70 @@
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/**
+ * What a source scan needs to see, and the anchors that keep it honest.
+ *
+ * Two guards in this package walk the source: `contract.test.ts` follows the
+ * relative import graph beneath `./contract`, and `no-app-imports.test.ts`
+ * scans every module for an app virtual specifier. They ask different
+ * questions of the same rule — WHICH MODULES DOES THIS ONE NAME — and each
+ * used to answer it with a pattern of its own. `contract.test.ts` found the
+ * defect in its copy and fixed it there:
+ *
+ *     "THREE import forms, because two of them used to be invisible here. The
+ *     pattern required the `from` keyword, so a side-effect import and a
+ *     dynamic one both walked past a guard whose whole job is to see them."
+ *
+ * The other copy was not fixed and still required `from`, so a dynamic import
+ * of an $app specifier walked past the gate that decides whether this package
+ * is publishable. Copying the lesson a third time is how a guard
+ * starts missing things again; the grammar lives here instead, and each guard
+ * filters the specifiers it cares about.
+ */
+/**
+ * Every module specifier a source file names, in all three forms a bundler
+ * follows: `from '…'` (import and re-export alike), a bare side-effect
+ * `import '…'`, and a dynamic `import('…')`.
+ *
+ * A type-only import is reported like any other. That is deliberate, and it
+ * is `contract.test.ts`'s standing argument: erasure is a build-time fact, and
+ * a pattern that has to understand `import type` is a pattern with a second
+ * way to be wrong.
+ */
+export function importSpecifiers(source) {
+    return [...source.matchAll(/(?:\bfrom|\bimport)\s*\(?\s*['"]([^'"]*)['"]/g)].map(([, specifier]) => specifier);
+}
+/**
+ * Every `.ts` and `.svelte` file beneath `root`, and the ones the walk MUST
+ * find.
+ *
+ * `mustReach` is a required argument for the reason `contract.test.ts` gives
+ * at length: an assertion over an empty list passes. `expect(offenders)
+ * .toEqual([])` is a clean bill of health over a walk that enumerated nothing
+ * — a directory renamed, a `readdirSync` that threw and was caught upstream,
+ * an entry filter that stopped matching — and a safety net that can narrow in
+ * silence reproduces the defect it exists to prevent. fndvit-website's
+ * `src/lib/testing/source-scan.ts` settled the shape: a scan cannot walk the
+ * tree without saying what it must find.
+ *
+ * Anchors are relative to `root` with `/` separators, so one representation
+ * crosses this interface and an anchor cannot silently fail to match an
+ * absolute path. A FLOOR was the alternative and is the thing being replaced:
+ * a walk that quietly stopped seeing two thirds of the tree clears any floor
+ * worth setting.
+ */
+export function sourceFiles(root, mustReach) {
+    const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            return walk(path);
+        return /\.(ts|svelte)$/.test(entry.name) ? [path] : [];
+    });
+    const files = walk(root);
+    const found = new Set(files.map((file) => relative(root, file).replaceAll('\\', '/')));
+    const missing = mustReach.filter((anchor) => !found.has(anchor));
+    if (missing.length > 0) {
+        throw new Error(`the source scan enumerated ${files.length} files but not ${missing.join(', ')} — ` +
+            'either the module moved or the walk stopped seeing it');
+    }
+    return files;
+}

package/dist/utils/document-title.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How a page names itself to the browser: `title — siteName`, or the site name
+ * alone.
+ *
+ * The format had two owners. `PageShell` composed it from `UiConfig.siteName`,
+ * and fndvit-website's `$lib/site` composed it again for the one page that
+ * cannot render through `PageShell` — its error page, whose centred layout is
+ * not one of the six variants. Both spelled the same expression, both
+ * comments noted that the other existed, and `site.test.ts` pinned the result
+ * as the literal `'Transparència — ViT'`: change the separator in the package
+ * and the error page drifts with nothing failing.
+ *
+ * It lives on `./contract` rather than in `UiConfig` because a config field
+ * would need a package DEFAULT, and that default is the expression — the
+ * duplication would survive the move. No host wants a separator of its own;
+ * one is a hypothetical seam.
+ *
+ * `siteName` is a parameter rather than a read, so this stays component-free
+ * and a server module can call it (fndvit-website's `$lib/site` supplies
+ * `SITE_NAME`, `PageShell` supplies `config.siteName`).
+ */
+export declare function documentTitle(title: string, siteName: string): string;

package/dist/utils/document-title.js

@@ -0,0 +1,27 @@
+/**
+ * How a page names itself to the browser: `title — siteName`, or the site name
+ * alone.
+ *
+ * The format had two owners. `PageShell` composed it from `UiConfig.siteName`,
+ * and fndvit-website's `$lib/site` composed it again for the one page that
+ * cannot render through `PageShell` — its error page, whose centred layout is
+ * not one of the six variants. Both spelled the same expression, both
+ * comments noted that the other existed, and `site.test.ts` pinned the result
+ * as the literal `'Transparència — ViT'`: change the separator in the package
+ * and the error page drifts with nothing failing.
+ *
+ * It lives on `./contract` rather than in `UiConfig` because a config field
+ * would need a package DEFAULT, and that default is the expression — the
+ * duplication would survive the move. No host wants a separator of its own;
+ * one is a hypothetical seam.
+ *
+ * `siteName` is a parameter rather than a read, so this stays component-free
+ * and a server module can call it (fndvit-website's `$lib/site` supplies
+ * `SITE_NAME`, `PageShell` supplies `config.siteName`).
+ */
+export function documentTitle(title, siteName) {
+    // An empty title is a REAL state, not a guard: pages title themselves from
+    // page copy and `content.getPage` returns '' for a missing row, so the site
+    // name alone must ship rather than a dangling separator.
+    return title ? `${title} — ${siteName}` : siteName;
+}

package/dist/utils/paths.d.ts

@@ -1,3 +1,30 @@
+/**
+ * The four path rules, and which doors they go out of.
+ *
+ * This note used to live in `index.ts` and argue that only `buildQueryString`
+ * was exported, that the other three were private, and that exporting them
+ * "would pin their behaviour into semver for no reader". All three claims had
+ * stopped being true:
+ *
+ * - `contract.ts` exports all four, and has since the subpath reached both
+ *   hosts.
+ * - Two of them DO have a host reader. fndvit-website's repository integration
+ *   suite asserts the `site_links.href` check constraint against
+ *   `isInternalPath` byte for byte, and the https columns against
+ *   `isExternalUrl` — that binding is the whole reason those cases exist, and
+ *   it is why these two belong on `./contract`: a CHECK constraint is a
+ *   server-side rule, and the classifier that has to agree with it must be
+ *   importable without loading a component.
+ * - fndvit-website does not re-export `buildQueryString` from its `nav.ts`
+ *   any more; that pass-through is deleted and its one reader imports the
+ *   package directly.
+ *
+ * What the old note got right is the principle, and `isPathUnder` is the name
+ * it applies to: it is the prefix match `Nav` and `Sidebar` highlight the
+ * current section with, both of them reach it by relative import, and no host
+ * has ever imported it. So it is the one of the four that stays in, held by
+ * `paths.test.ts` rather than by semver.
+ */
 /** Prefix match over a URL pathname: '/what-we-do' covers '/what-we-do/<slug>'. */
 export declare function isPathUnder(pathname: string, prefix: string): boolean;
 /**

package/dist/utils/paths.js

@@ -1,3 +1,30 @@
+/**
+ * The four path rules, and which doors they go out of.
+ *
+ * This note used to live in `index.ts` and argue that only `buildQueryString`
+ * was exported, that the other three were private, and that exporting them
+ * "would pin their behaviour into semver for no reader". All three claims had
+ * stopped being true:
+ *
+ * - `contract.ts` exports all four, and has since the subpath reached both
+ *   hosts.
+ * - Two of them DO have a host reader. fndvit-website's repository integration
+ *   suite asserts the `site_links.href` check constraint against
+ *   `isInternalPath` byte for byte, and the https columns against
+ *   `isExternalUrl` — that binding is the whole reason those cases exist, and
+ *   it is why these two belong on `./contract`: a CHECK constraint is a
+ *   server-side rule, and the classifier that has to agree with it must be
+ *   importable without loading a component.
+ * - fndvit-website does not re-export `buildQueryString` from its `nav.ts`
+ *   any more; that pass-through is deleted and its one reader imports the
+ *   package directly.
+ *
+ * What the old note got right is the principle, and `isPathUnder` is the name
+ * it applies to: it is the prefix match `Nav` and `Sidebar` highlight the
+ * current section with, both of them reach it by relative import, and no host
+ * has ever imported it. So it is the one of the four that stays in, held by
+ * `paths.test.ts` rather than by semver.
+ */
 /** Prefix match over a URL pathname: '/what-we-do' covers '/what-we-do/<slug>'. */
 export function isPathUnder(pathname, prefix) {
     return pathname === prefix || pathname.startsWith(`${prefix}/`);

package/dist/utils/weekly-list-contract.d.ts

@@ -64,3 +64,38 @@ export interface WeeklyListServerData {
     pageSize: number;
     query: WeeklyListFilters;
 }
+/**
+ * The four params this list travels as, in the order a URL reads.
+ *
+ * Exported so a host's query schema can be bound to them rather than agreeing
+ * by coincidence: fndvit-website's `weeklyListQuerySchema` names all four as
+ * zod fields, and nothing said they were these four.
+ */
+export declare const WEEKLY_LIST_PARAMS: readonly ["q", "theme", "sort", "page"];
+/**
+ * The READ half of the weeklies URL contract — what a URL this package wrote
+ * means when it comes back.
+ *
+ * `WEEKLY_LIST_DEFAULTS` gave the VALUES one owner and both hosts derive from
+ * it correctly. The param NAMES and the parse had none: they were spelled four
+ * times across three repositories — `toQuery`/`hrefFor` here, a `parseListUrl`
+ * declared inside this package's own test, `weeklyListQuerySchema` in
+ * fndvit-website and `weeklyQuery` in vit-brain — and the two repositories
+ * cannot import each other, so nothing could disagree out loud. vit-brain's
+ * docblock states the failure exactly: rename a param here and the read side
+ * drops the filter silently while the write side keeps producing it.
+ *
+ * Worse, the round-trip case that exists to catch precisely that
+ * ("builds URLs that parse back to the filters they were built from") crossed
+ * the write half against the stand-in in the test file, not against either
+ * real reader. It could not fail for the reason it was written.
+ *
+ * TOLERANT, because these URLs are shared and hand-edited: an unknown sort or
+ * a junk page falls back to its default rather than refusing the page. A host
+ * may still layer its own tolerance on top — fndvit-website trims and caps
+ * lengths in zod, vit-brain clamps nothing further — but the names, and what
+ * an absent or bad value means, are answered once, here.
+ */
+export declare function parseWeeklyListUrl(url: URL | string): WeeklyListFilters & {
+    page: number;
+};

package/dist/utils/weekly-list-contract.js

@@ -40,3 +40,49 @@
  * is the value it should answer unless it means to differ.
  */
 export const WEEKLY_LIST_DEFAULTS = { sort: 'desc', page: 1, pageSize: 12 };
+/**
+ * The four params this list travels as, in the order a URL reads.
+ *
+ * Exported so a host's query schema can be bound to them rather than agreeing
+ * by coincidence: fndvit-website's `weeklyListQuerySchema` names all four as
+ * zod fields, and nothing said they were these four.
+ */
+export const WEEKLY_LIST_PARAMS = ['q', 'theme', 'sort', 'page'];
+/**
+ * The READ half of the weeklies URL contract — what a URL this package wrote
+ * means when it comes back.
+ *
+ * `WEEKLY_LIST_DEFAULTS` gave the VALUES one owner and both hosts derive from
+ * it correctly. The param NAMES and the parse had none: they were spelled four
+ * times across three repositories — `toQuery`/`hrefFor` here, a `parseListUrl`
+ * declared inside this package's own test, `weeklyListQuerySchema` in
+ * fndvit-website and `weeklyQuery` in vit-brain — and the two repositories
+ * cannot import each other, so nothing could disagree out loud. vit-brain's
+ * docblock states the failure exactly: rename a param here and the read side
+ * drops the filter silently while the write side keeps producing it.
+ *
+ * Worse, the round-trip case that exists to catch precisely that
+ * ("builds URLs that parse back to the filters they were built from") crossed
+ * the write half against the stand-in in the test file, not against either
+ * real reader. It could not fail for the reason it was written.
+ *
+ * TOLERANT, because these URLs are shared and hand-edited: an unknown sort or
+ * a junk page falls back to its default rather than refusing the page. A host
+ * may still layer its own tolerance on top — fndvit-website trims and caps
+ * lengths in zod, vit-brain clamps nothing further — but the names, and what
+ * an absent or bad value means, are answered once, here.
+ */
+export function parseWeeklyListUrl(url) {
+    // A relative href (`hrefFor` writes one) needs a base to parse against; it
+    // is never read, only discarded with the rest of the origin.
+    const params = (typeof url === 'string' ? new URL(url, 'https://weekly-list.invalid') : url)
+        .searchParams;
+    const sort = params.get('sort');
+    const page = Math.trunc(Number(params.get('page')));
+    return {
+        q: params.get('q') ?? '',
+        theme: params.get('theme'),
+        sort: sort === 'asc' || sort === 'desc' ? sort : WEEKLY_LIST_DEFAULTS.sort,
+        page: page >= WEEKLY_LIST_DEFAULTS.page ? page : WEEKLY_LIST_DEFAULTS.page
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vit-foundation/ui",
-	"version": "0.22.0",
+	"version": "0.24.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",

package/dist/components/admin/AdminShell.svelte

@@ -1,42 +0,0 @@
-<script lang="ts">
-	import type { Snippet } from 'svelte';
-	import Sidebar, { type SidebarItem } from './Sidebar.svelte';
-
-	interface Props {
-		/** Rail entries, already permission-filtered by the host. */
-		items: SidebarItem[];
-		/** Accessible name of the sidebar nav landmark. */
-		navLabel?: string;
-		logo?: Snippet;
-		/** Bottom of the rail — the host's logout form. */
-		footer?: Snippet;
-		/** The page content. */
-		children: Snippet;
-		/** Highlighting override for tests and stories. */
-		url?: URL;
-	}
-
-	let { items, navLabel = 'Principal', logo, footer, children, url = undefined }: Props = $props();
-</script>
-
-<div class="shell">
-	<Sidebar {items} label={navLabel} {logo} {footer} {url} />
-	<main class="content">
-		{@render children()}
-	</main>
-</div>
-
-<style>
-	/* The sidebar is fixed at 4.5rem; the content pays for it once, here,
-	   instead of every page knowing the rail's width. */
-	.content {
-		margin-left: 4.5rem;
-		min-height: 100vh;
-	}
-
-	@media print {
-		.content {
-			margin-left: 0;
-		}
-	}
-</style>

package/dist/components/admin/AdminShell.svelte.d.ts

@@ -1,18 +0,0 @@
-import type { Snippet } from 'svelte';
-import { type SidebarItem } from './Sidebar.svelte';
-interface Props {
-    /** Rail entries, already permission-filtered by the host. */
-    items: SidebarItem[];
-    /** Accessible name of the sidebar nav landmark. */
-    navLabel?: string;
-    logo?: Snippet;
-    /** Bottom of the rail — the host's logout form. */
-    footer?: Snippet;
-    /** The page content. */
-    children: Snippet;
-    /** Highlighting override for tests and stories. */
-    url?: URL;
-}
-declare const AdminShell: import("svelte").Component<Props, {}, "">;
-type AdminShell = ReturnType<typeof AdminShell>;
-export default AdminShell;