@vit-foundation/ui 0.15.0 → 0.16.0

package/dist/edit/chrome/PropertyRow.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
 	import { getUiConfig } from '../../config/context.js';
+	import type { ParameterlessKey } from '../../config/types.js';
 	import { getEditAdapter } from '../context.js';
-	import type { PropertyDescriptor } from '../types.js';
+	import type { PropertyDescriptor, PropertyValue } from '../types.js';
 
 	/**
 	 * One property of an EditPanel: label, a control by `descriptor.type`, and
@@ -11,10 +12,14 @@
 	 *
 	 * The row assumes an adapter with `saveProperty` exists — EditPanel only
 	 * renders when the frame's triple gate already established both.
+	 *
+	 * The control state is text throughout — a flag's boolean rides as
+	 * 'true'/'false' in its <select> and becomes a boolean again only at the
+	 * adapter boundary, so one draft/saved pair serves every type.
 	 */
 	interface Props {
 		descriptor: PropertyDescriptor;
-		value: string | null;
+		value: PropertyValue;
 	}
 
 	let { descriptor, value }: Props = $props();
@@ -22,21 +27,28 @@
 	const adapter = getEditAdapter();
 	const config = getUiConfig();
 
+	/** The control's reading of a property value. */
+	const asText = (next: PropertyValue): string =>
+		typeof next === 'boolean' ? String(next) : (next ?? '');
+
+	/** A flag state's wording, from the same catalog the site renders. */
+	const wording = (key: ParameterlessKey): string => config.messages[key]?.() ?? key;
+
 	let status = $state<'idle' | 'dirty' | 'saving' | 'error'>('idle');
 	let announcement = $state('');
 	/** Last persisted value, what a failed draft is measured against. */
 	// svelte-ignore state_referenced_locally
-	let savedValue = $state(value ?? '');
+	let savedValue = $state(asText(value));
 	// svelte-ignore state_referenced_locally
-	let draft = $state(value ?? '');
+	let draft = $state(asText(value));
 	let fileInput: HTMLInputElement | undefined = $state();
 
 	// Follow the prop only while idle — never repaint a held draft (the
 	// Editable rule).
 	// svelte-ignore state_referenced_locally
-	let lastPropValue = $state(value ?? '');
+	let lastPropValue = $state(asText(value));
 	$effect(() => {
-		const next = value ?? '';
+		const next = asText(value);
 		if (next !== lastPropValue) {
 			lastPropValue = next;
 			if (status === 'idle') {
@@ -46,14 +58,14 @@
 		}
 	});
 
-	async function persist(next: string | null): Promise<void> {
+	async function persist(next: PropertyValue): Promise<void> {
 		if (!adapter?.saveProperty) return;
 		status = 'saving';
 		announcement = config.editMessages.edit_saving();
 		try {
 			await adapter.saveProperty(descriptor, next);
-			savedValue = next ?? '';
-			draft = next ?? '';
+			savedValue = asText(next);
+			draft = asText(next);
 			status = 'idle';
 			announcement = config.editMessages.edit_saved();
 		} catch {
@@ -69,6 +81,10 @@
 			status = 'idle';
 			return;
 		}
+		if (descriptor.type === 'flag') {
+			void persist(trimmed === 'true');
+			return;
+		}
 		if (trimmed === '') {
 			if (!descriptor.nullable) {
 				status = 'error';
@@ -122,6 +138,21 @@
 				<option value={option.value}>{option.label}</option>
 			{/each}
 		</select>
+	{:else if descriptor.type === 'flag'}
+		<!-- Two states, worded from the catalog: the host names the pair
+		     (published/draft, open/closed), the adapter receives a boolean. -->
+		<select
+			{id}
+			data-vit-editing={status}
+			value={draft}
+			onchange={(event) => {
+				draft = event.currentTarget.value;
+				commit();
+			}}
+		>
+			<option value="true">{wording(descriptor.on ?? 'status_published')}</option>
+			<option value="false">{wording(descriptor.off ?? 'status_draft')}</option>
+		</select>
 	{:else if descriptor.type === 'image'}
 		{#if savedValue}
 			<img class="thumb" src={savedValue} alt="" />

package/dist/edit/chrome/PropertyRow.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { PropertyDescriptor } from '../types.js';
+import type { PropertyDescriptor, PropertyValue } from '../types.js';
 /**
  * One property of an EditPanel: label, a control by `descriptor.type`, and
  * its own commit lifecycle — Editable's state machine, panel-shaped. Each
@@ -7,10 +7,14 @@ import type { PropertyDescriptor } from '../types.js';
  *
  * The row assumes an adapter with `saveProperty` exists — EditPanel only
  * renders when the frame's triple gate already established both.
+ *
+ * The control state is text throughout — a flag's boolean rides as
+ * 'true'/'false' in its <select> and becomes a boolean again only at the
+ * adapter boundary, so one draft/saved pair serves every type.
  */
 interface Props {
     descriptor: PropertyDescriptor;
-    value: string | null;
+    value: PropertyValue;
 }
 declare const PropertyRow: import("svelte").Component<Props, {}, "">;
 type PropertyRow = ReturnType<typeof PropertyRow>;

package/dist/edit/collection.svelte.d.ts

@@ -0,0 +1,49 @@
+import type { CollectionRef, EntityOp } from './types.js';
+type CreateOp = Extract<EntityOp, {
+    kind: 'create';
+}>;
+type RemoveOp = Extract<EntityOp, {
+    kind: 'remove';
+}>;
+/** An edit map a list may inject removal into. */
+export interface RemovableMap {
+    /** Set by the list from its `collection` — removal of this row. */
+    removeOp?: RemoveOp;
+}
+/**
+ * The structural half of one editable LIST, as its template reads it.
+ * Both members answer `undefined` while the collection is not live, so the
+ * template's `{#if}` is the whole gate.
+ */
+export interface CollectionEditing<Row, Map extends RemovableMap> {
+    /** The create op for the add slot at the end of the list. */
+    readonly add: CreateOp | undefined;
+    /** The create op for an add slot anchored before one row (Timeline). */
+    addBefore(id: string | number): CreateOp | undefined;
+    /**
+     * The host's map for one row, plus the remove op the LIST injects — lists
+     * own identity, so a host never spells a removal. Rows without an `id`
+     * keep the host's map untouched: a remove op needs an identity, and
+     * read-only hosts never pass one.
+     */
+    mapFor(row: Row): Map | undefined;
+}
+/**
+ * What every list with a `collection` prop used to repeat — Timeline,
+ * CollaboratorList, JobList, Nav and Footer each carried the triple gate
+ * (collection named ∧ adapter editing ∧ `applyOp` present) and the same
+ * remove-op injection, five times verbatim. One helper, one place to keep
+ * the rule: a structural affordance renders only when all three hold.
+ *
+ * `read` is a thunk over the list's props so both stay reactive; the
+ * adapter comes from context, so call this during component init like
+ * `getEditAdapter` itself.
+ */
+export declare function collectionEditing<Row extends {
+    id?: string | number;
+}, Map extends RemovableMap>(read: () => {
+    collection: CollectionRef | undefined;
+    /** The host's per-row map (`editFor`, or Nav/Footer's `propertiesFor`). */
+    editFor: ((row: Row) => Map | undefined) | undefined;
+}): CollectionEditing<Row, Map>;
+export {};

package/dist/edit/collection.svelte.js

@@ -0,0 +1,39 @@
+import { getEditAdapter } from './context.js';
+/**
+ * What every list with a `collection` prop used to repeat — Timeline,
+ * CollaboratorList, JobList, Nav and Footer each carried the triple gate
+ * (collection named ∧ adapter editing ∧ `applyOp` present) and the same
+ * remove-op injection, five times verbatim. One helper, one place to keep
+ * the rule: a structural affordance renders only when all three hold.
+ *
+ * `read` is a thunk over the list's props so both stay reactive; the
+ * adapter comes from context, so call this during component init like
+ * `getEditAdapter` itself.
+ */
+export function collectionEditing(read) {
+    const adapter = getEditAdapter();
+    const live = $derived.by(() => {
+        const { collection } = read();
+        return collection !== undefined &&
+            (adapter?.isEditing ?? false) &&
+            adapter?.applyOp !== undefined
+            ? collection
+            : undefined;
+    });
+    return {
+        get add() {
+            return live ? { kind: 'create', collection: live } : undefined;
+        },
+        addBefore(id) {
+            return live
+                ? { kind: 'create', collection: live, anchor: { id, placement: 'before' } }
+                : undefined;
+        },
+        mapFor(row) {
+            const map = read().editFor?.(row);
+            if (!live || row.id === undefined)
+                return map;
+            return { ...map, removeOp: { kind: 'remove', collection: live, id: row.id } };
+        }
+    };
+}

package/dist/edit/helpers.d.ts

@@ -1,13 +1,12 @@
-import type { Locale } from '../config/types.js';
+import type { Locale, NotParameterized, ParameterlessKey } from '../config/types.js';
 import type { CollectionRef, EditableEntity, EditDescriptor, PropertyDescriptor } from './types.js';
 /** Everything a property descriptor carries beyond its ref. */
 type PropertySpec = Omit<PropertyDescriptor, 'ref'>;
 /**
  * Descriptor for one interface-wording message (a Paraglide catalog key).
- * Only parameterless messages are sensibly editable in place — editing the
- * RENDERED text of a parameterized one would overwrite its template.
+ * The key type carries the rule — see `ParameterlessKey` in ../config/types.js.
  */
-export declare function chromeEdit(key: string, locale: Locale, options?: {
+export declare function chromeEdit(key: ParameterlessKey, locale: Locale, options?: {
     format?: EditDescriptor['format'];
     label?: string;
 }): EditDescriptor;
@@ -38,8 +37,9 @@ export declare function entityProperty(entity: EditableEntity, id: string | numb
 /**
  * A panel property over one interface-wording message — how strings that can
  * never hold a caret (an `<option>` label, an input placeholder) still edit.
+ * Accepts the site's own keys too; see `NotParameterized` in ../config/types.js.
  */
-export declare function chromeProperty(key: string, spec: PropertySpec): PropertyDescriptor;
+export declare function chromeProperty<K extends string>(key: NotParameterized<K>, spec: PropertySpec): PropertyDescriptor;
 /** Names one entity collection at one render site. */
 export declare function collectionOf(entity: EditableEntity, scope?: string): CollectionRef;
 export {};

package/dist/edit/helpers.js

@@ -1,7 +1,6 @@
 /**
  * Descriptor for one interface-wording message (a Paraglide catalog key).
- * Only parameterless messages are sensibly editable in place — editing the
- * RENDERED text of a parameterized one would overwrite its template.
+ * The key type carries the rule — see `ParameterlessKey` in ../config/types.js.
  */
 export function chromeEdit(key, locale, options) {
     return { ref: { kind: 'chrome', key }, locale, ...options };
@@ -33,6 +32,7 @@ export function entityProperty(entity, id) {
 /**
  * A panel property over one interface-wording message — how strings that can
  * never hold a caret (an `<option>` label, an input placeholder) still edit.
+ * Accepts the site's own keys too; see `NotParameterized` in ../config/types.js.
  */
 export function chromeProperty(key, spec) {
     return { ref: { kind: 'chrome', key }, ...spec };

package/dist/edit/index.d.ts

@@ -1,4 +1,6 @@
 export { getEditAdapter, setEditAdapter } from './context.js';
+export { collectionEditing } from './collection.svelte.js';
+export type { CollectionEditing, RemovableMap } from './collection.svelte.js';
 export { default as ActionLabel } from './ActionLabel.svelte';
 export { default as Editable } from './Editable.svelte';
 export { default as AddSlot } from './chrome/AddSlot.svelte';
@@ -10,4 +12,5 @@ export { default as EditPopover } from './chrome/EditPopover.svelte';
 export { default as LinkEdit } from './chrome/LinkEdit.svelte';
 export { chromeEdit, chromeProperty, collectionOf, entityEdit, entityProperty, pageCopyEdit } from './helpers.js';
 export { localize } from './types.js';
-export type { CollectionRef, ContentRef, EditableEntity, EditAdapter, EditDescriptor, EntityOp, LocalizedText, PropertyDescriptor, PropertyOption, PropertyType } from './types.js';
+export type { CollectionRef, ContentRef, EditableEntity, EditAdapter, EditDescriptor, EntityOp, LocalizedText, PropertyDescriptor, PropertyOption, PropertyType, PropertyValue } from './types.js';
+export type { NotParameterized, ParameterlessKey } from '../config/types.js';

package/dist/edit/index.js

@@ -1,4 +1,5 @@
 export { getEditAdapter, setEditAdapter } from './context.js';
+export { collectionEditing } from './collection.svelte.js';
 export { default as ActionLabel } from './ActionLabel.svelte';
 export { default as Editable } from './Editable.svelte';
 export { default as AddSlot } from './chrome/AddSlot.svelte';

package/dist/edit/types.d.ts

@@ -1,4 +1,4 @@
-import type { Locale } from '../config/types.js';
+import type { Locale, ParameterlessKey } from '../config/types.js';
 /**
  * The stored shape of one localized text column (`jsonb` keyed by locale).
  * Catalan is canonical and required — the database enforces `content ? 'ca'`
@@ -52,12 +52,19 @@ export interface EditDescriptor {
     label?: string;
 }
 /**
- * The value kinds a property panel can edit. Everything in this content model
- * serializes to a string on the wire — an ISO date, a URL, an enum member, a
- * storage path — so there is no typed value union: the ADAPTER parses, and
- * the host's schemas stay the sole validators.
+ * The value kinds a property panel can edit. All but one serialize to a
+ * string on the wire — an ISO date, a URL, an enum member, a storage path —
+ * so the ADAPTER parses and the host's schemas stay the sole validators. The
+ * exception is `flag`: a two-state row whose value IS a boolean (published or
+ * not, open or not), so no host has to spell a 'true'/'false' select and no
+ * card has to derive one from its data.
  */
-export type PropertyType = 'text' | 'url' | 'date' | 'select' | 'image';
+export type PropertyType = 'text' | 'url' | 'date' | 'select' | 'image' | 'flag';
+/**
+ * What a property row hands the adapter: a string for every type but `flag`,
+ * a boolean for a flag, `null` when a `nullable` property is cleared.
+ */
+export type PropertyValue = string | boolean | null;
 /** One choice of a `select` property. */
 export interface PropertyOption {
     value: string;
@@ -77,6 +84,13 @@ export interface PropertyDescriptor {
     label: string;
     /** Required when `type` is 'select'. */
     options?: readonly PropertyOption[];
+    /**
+     * 'flag' only: the catalog keys wording each state, so the same row reads
+     * «Publicat / Esborrany» on a card and «Oberta / Tancada» on an opening.
+     * Default `status_published` / `status_draft`.
+     */
+    on?: ParameterlessKey;
+    off?: ParameterlessKey;
     placeholder?: string;
     /** Clearing the field saves null (linkUrl, externalUrl). */
     nullable?: boolean;
@@ -135,10 +149,11 @@ export interface EditAdapter {
     readonly isEditing: boolean;
     save(descriptor: EditDescriptor, value: string): Promise<void>;
     /**
-     * Panel property save. The value stays a string on the wire (ISO date,
-     * url, enum member, image path); `null` clears a `nullable` property.
+     * Panel property save. A string on the wire for every type but `flag`
+     * (ISO date, url, enum member, image path), a boolean for a flag; `null`
+     * clears a `nullable` property.
      */
-    saveProperty?(descriptor: PropertyDescriptor, value: string | null): Promise<void>;
+    saveProperty?(descriptor: PropertyDescriptor, value: PropertyValue): Promise<void>;
     /**
      * Structural collection ops. `create` may resolve the new row's id so the
      * UI can point at it after the host's refresh.

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export * from './admin.js';
 export * from './forms/index.js';
 export * from './config/index.js';
 export * from './edit/index.js';
-export { isPathUnder } from './utils/paths.js';
+export { buildQueryString, isPathUnder } from './utils/paths.js';

package/dist/index.js

@@ -12,5 +12,5 @@ export * from './forms/index.js';
 // App wiring: configuration context and the edit-mode contract.
 export * from './config/index.js';
 export * from './edit/index.js';
-// Path utility shared with host apps.
-export { isPathUnder } from './utils/paths.js';
+// Path utilities shared with host apps.
+export { buildQueryString, isPathUnder } from './utils/paths.js';

package/dist/utils/milestones.d.ts

@@ -7,5 +7,20 @@ import type { MilestoneCategory } from '../content/types.js';
  * tokens.css.
  */
 export declare const MILESTONE_CATEGORY_COLOR: Record<MilestoneCategory, string>;
+/**
+ * The transparency page's client-side filter: the timeline is small enough
+ * to filter in the browser (a choice its load function records), and this is
+ * the predicate — named and tested here rather than closing over a page's
+ * `data` inside a `$derived`. Category is exact; the query is a trimmed,
+ * case-insensitive substring of title + body.
+ */
+export declare function matchesMilestoneFilter(milestone: {
+    title: string;
+    body: string | null;
+    category: MilestoneCategory;
+}, filter: {
+    q: string;
+    category: MilestoneCategory | null;
+}): boolean;
 /** The category's label in the host app's copy. */
 export declare function milestoneCategoryLabel(category: MilestoneCategory, messages: UiMessages): string;

package/dist/utils/milestones.js

@@ -11,6 +11,23 @@ export const MILESTONE_CATEGORY_COLOR = {
     collaboration: 'var(--series-4)',
     press: 'var(--series-5)'
 };
+/**
+ * The transparency page's client-side filter: the timeline is small enough
+ * to filter in the browser (a choice its load function records), and this is
+ * the predicate — named and tested here rather than closing over a page's
+ * `data` inside a `$derived`. Category is exact; the query is a trimmed,
+ * case-insensitive substring of title + body.
+ */
+export function matchesMilestoneFilter(milestone, filter) {
+    if (filter.category && milestone.category !== filter.category)
+        return false;
+    if (!filter.q)
+        return true;
+    const needle = filter.q.trim().toLowerCase();
+    if (!needle)
+        return true;
+    return `${milestone.title} ${milestone.body ?? ''}`.toLowerCase().includes(needle);
+}
 /** The category's label in the host app's copy. */
 export function milestoneCategoryLabel(category, messages) {
     switch (category) {

package/dist/utils/paths.d.ts

@@ -1,2 +1,8 @@
 /** Prefix match over a URL pathname: '/what-we-do' covers '/what-we-do/<slug>'. */
 export declare function isPathUnder(pathname: string, prefix: string): boolean;
+/**
+ * Builds "?a=1&b=2" from the truthy entries, or "" when none remain — the one
+ * way a filter or a page number joins a canonical path, so the URL a list
+ * mirrors and the hrefs it renders are spelled by the same function.
+ */
+export declare function buildQueryString(params: Record<string, string | null | undefined>): string;

package/dist/utils/paths.js

@@ -2,3 +2,17 @@
 export function isPathUnder(pathname, prefix) {
     return pathname === prefix || pathname.startsWith(`${prefix}/`);
 }
+/**
+ * Builds "?a=1&b=2" from the truthy entries, or "" when none remain — the one
+ * way a filter or a page number joins a canonical path, so the URL a list
+ * mirrors and the hrefs it renders are spelled by the same function.
+ */
+export function buildQueryString(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value)
+            search.set(key, value);
+    }
+    const encoded = search.toString();
+    return encoded ? `?${encoded}` : '';
+}

package/dist/utils/url-filters.svelte.d.ts

@@ -0,0 +1,58 @@
+export interface UrlFiltersConfig<T extends Record<string, unknown>> {
+    /** Unlocalized path the query string is appended to. */
+    path: string;
+    /**
+     * The server-rendered values. A thunk so callers reference props in a
+     * closure; read inside an effect, so it tracks them and re-seeds when a
+     * navigation changes what the server sent.
+     */
+    initial: () => T;
+    /** Which values ride the URL. Null/undefined/empty entries are dropped. */
+    toQuery: (values: T) => Record<string, string | null | undefined>;
+    /** Runs after the URL is mirrored; omit for purely client-side filtering. */
+    onChange?: () => void;
+    /**
+     * How a mirrored URL is written. Required, not defaulted: shallow routing
+     * is the host's router's (SvelteKit's `replaceState` through its locale
+     * prefixing), and the package has no router — the same reason hrefs
+     * resolve through `UiConfig.href`.
+     */
+    replaceUrl: (path: string) => void;
+}
+export interface UrlFilters<T extends Record<string, unknown>> {
+    /** Current filter values, for the controls to render. */
+    readonly values: T;
+    /**
+     * The params riding the URL for the current values. Exposed so a caller
+     * can build a URL that carries the filters plus something of its own —
+     * the weeklies index adds a page number. What that extra means, and when
+     * it survives a filter change, is the caller's rule.
+     */
+    readonly query: Record<string, string | null | undefined>;
+    /** Applies a change, mirrors it into the URL, then notifies. */
+    update(patch: Partial<T>): void;
+}
+/**
+ * Filter state that lives in the URL, in both directions: seeded from the
+ * values the server rendered, mirrored back on every client change so the
+ * page stays deep-linkable, and re-seeded whenever the server sends
+ * different ones.
+ *
+ * The site's /weeklies and /transparency each wrote this by hand — the
+ * seeding, the mirroring, and a handful of `state_referenced_locally`
+ * suppressions apiece. `initial` is a thunk, so a page reads its
+ * server-rendered data inside a closure, which is what the compiler asked for.
+ *
+ * The client→URL direction alone was not enough. Read once, `initial` left a
+ * same-route navigation carrying different filters — the header's own
+ * "Weeklies" link, followed from /weeklies?theme=salut — with the controls
+ * displaying the previous filter while the page below showed the server's
+ * unfiltered answer. Which surface went stale differed per caller: one
+ * contradicted its own chips, the other kept filtering by a chip the URL no
+ * longer carried. One rule, two symptoms, so it lives here and not in either.
+ *
+ * What a page does *with* a change stays the page's — refetch through a
+ * remote function, or filter a list it already has — which is why this owns
+ * the URL and not the filtering.
+ */
+export declare function createUrlFilters<T extends Record<string, unknown>>(config: UrlFiltersConfig<T>): UrlFilters<T>;

package/dist/utils/url-filters.svelte.js

@@ -0,0 +1,47 @@
+import { buildQueryString } from './paths.js';
+/**
+ * Filter state that lives in the URL, in both directions: seeded from the
+ * values the server rendered, mirrored back on every client change so the
+ * page stays deep-linkable, and re-seeded whenever the server sends
+ * different ones.
+ *
+ * The site's /weeklies and /transparency each wrote this by hand — the
+ * seeding, the mirroring, and a handful of `state_referenced_locally`
+ * suppressions apiece. `initial` is a thunk, so a page reads its
+ * server-rendered data inside a closure, which is what the compiler asked for.
+ *
+ * The client→URL direction alone was not enough. Read once, `initial` left a
+ * same-route navigation carrying different filters — the header's own
+ * "Weeklies" link, followed from /weeklies?theme=salut — with the controls
+ * displaying the previous filter while the page below showed the server's
+ * unfiltered answer. Which surface went stale differed per caller: one
+ * contradicted its own chips, the other kept filtering by a chip the URL no
+ * longer carried. One rule, two symptoms, so it lives here and not in either.
+ *
+ * What a page does *with* a change stays the page's — refetch through a
+ * remote function, or filter a list it already has — which is why this owns
+ * the URL and not the filtering.
+ */
+export function createUrlFilters(config) {
+    const values = $state({ ...config.initial() });
+    // A client change mirrors through replaceState, which does not re-run the
+    // load — so `initial()` still reports what the server last sent and this
+    // does not fight the reader's own filtering. It fires on a real
+    // navigation, exactly when the controls would otherwise keep old filters.
+    $effect(() => {
+        Object.assign(values, config.initial());
+    });
+    return {
+        get values() {
+            return values;
+        },
+        get query() {
+            return config.toQuery(values);
+        },
+        update(patch) {
+            Object.assign(values, patch);
+            config.replaceUrl(`${config.path}${buildQueryString(config.toQuery(values))}`);
+            config.onChange?.();
+        }
+    };
+}

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

@@ -0,0 +1,82 @@
+import type { Locale } from '../config/types.js';
+import type { SortDirection, WeeklyCardData } from '../content/types.js';
+/**
+ * The weeklies index's URL defaults: the value a param stands for when it is
+ * absent. Both halves of the URL contract — this module omitting a default,
+ * the host's query schema supplying one — must name the same values, so a
+ * host derives its schema defaults from here rather than restating them.
+ */
+export declare const WEEKLY_LIST_DEFAULTS: {
+    readonly sort: "desc";
+    readonly page: 1;
+};
+/** A type alias, not an interface: createUrlFilters needs an index signature. */
+export type WeeklyListFilters = {
+    q: string;
+    theme: string | null;
+    sort: SortDirection;
+};
+/** One page of the list plus the unpaged total (for the pagination). */
+export interface WeeklyListPage {
+    items: WeeklyCardData[];
+    total: number;
+}
+/** The server-rendered page, re-read on every navigation. */
+export interface WeeklyListServerData {
+    weeklies: WeeklyCardData[];
+    total: number;
+    page: number;
+    pageSize: number;
+    query: WeeklyListFilters;
+}
+export interface WeeklyListConfig {
+    /** Reads the route's `data`; called inside an effect, so it tracks it. */
+    server: () => WeeklyListServerData;
+    /**
+     * Fetches the first page of a filter — the host's remote query. Required,
+     * like `locale` and `replaceUrl`: the package never talks to a backend, an
+     * i18n runtime or a router, so the site hands in its own three.
+     */
+    fetchPage: (input: {
+        q?: string;
+        theme?: string | null;
+        sort: SortDirection;
+        limit: number;
+        locale: Locale;
+    }) => Promise<WeeklyListPage>;
+    /** The locale being rendered. Reactive read. */
+    locale: () => Locale;
+    /** Shallow-routing URL write — see UrlFiltersConfig.replaceUrl. */
+    replaceUrl: (path: string) => void;
+}
+export interface WeeklyList {
+    readonly items: WeeklyCardData[];
+    readonly total: number;
+    /** A client-side refetch always shows the first page of the new filter. */
+    readonly page: number;
+    readonly isLoading: boolean;
+    readonly loadError: boolean;
+    /** Current filter values, for the controls to render. */
+    readonly filters: WeeklyListFilters;
+    /** Href for a 1-based page, carrying the active filters. */
+    hrefFor(page: number): string;
+    /** Applies a filter change: mirrors the URL, then refetches page one. */
+    update(patch: Partial<WeeklyListFilters>): void;
+}
+/**
+ * The weeklies index view: the filters that ride the URL, the page the
+ * server rendered, and the page a filter change refetched in place.
+ *
+ * The two disagree by design — a changed filter returns to the first page
+ * while the URL still carries the old one — and reconciling them was four
+ * `$state` cells, an `$effect` and three `$derived` sitting in a route file,
+ * where nothing could reach them. Two things went wrong there: `loadError`
+ * was never cleared on navigation, so a failed refetch kept its alert on
+ * screen above fresh results; and a failed refetch left the URL, the grid
+ * and the pagination status giving three different answers.
+ *
+ * `createUrlFilters` owns the URL and deliberately not the fetching, because
+ * the transparency page filters client-side over data it already has. This
+ * owns the fetching and the reconciliation, for the one page that does both.
+ */
+export declare function createWeeklyList(config: WeeklyListConfig): WeeklyList;