emdash 0.35.0 → 0.37.0

package/src/client/index.ts

@@ -193,13 +193,28 @@ export interface MediaItem {
 	size: number;
 	width?: number;
 	height?: number;
+	focalX?: number | null;
+	focalY?: number | null;
 	alt?: string;
 	caption?: string;
 	createdAt: string;
 	updatedAt: string;
+	folderId?: string | null;
 	usage?: MediaUsageSummary;
 }
 
+/** Result of assigning local media to a folder or the Main library */
+export interface MediaFolderAssignment {
+	id: string;
+	folderId: string | null;
+}
+
+/** Flat media-library folder */
+export interface MediaFolder {
+	id: string;
+	name: string;
+}
+
 /** Media usage repair request */
 export type MediaUsageRepairInput = { scope: "collection"; collection: string } | { scope: "all" };
 
@@ -229,6 +244,18 @@ export interface MediaUsageRepairResponse {
 	collections: MediaUsageRepairCollectionSummary[];
 }
 
+export interface MediaUsageProgress {
+	status: "indexing" | "ready" | "needs_attention";
+	readyCollections: number;
+	totalCollections: number;
+}
+
+export interface MediaUsageProgressAdvanceResponse {
+	activation: MediaUsageActivationStatus;
+	progress: MediaUsageProgress | null;
+	nextRequestInMs: 0 | 30_000 | null;
+}
+
 /** Durable media usage entry-work state */
 export type MediaUsageWorkState = "pending" | "retry" | "leased" | "failed";
 
@@ -272,6 +299,28 @@ export interface MediaUsageWorkRetryResponse {
 	item: MediaUsageWorkItem;
 }
 
+export interface MediaUsageActivationStatus {
+	state: "expanded" | "activating" | "active";
+	collectionCursor: string | null;
+	attemptCount: number;
+	drainConfirmedAt: string | null;
+	lastAttemptedAt: string | null;
+	lastErrorCode: "MEDIA_USAGE_ACTIVATION_FAILED" | null;
+	leaseExpiresAt: string | null;
+	activatedAt: string | null;
+	updatedAt: string;
+}
+
+export interface MediaUsageActivationAdvanceInput {
+	writersDrained: true;
+}
+
+export interface MediaUsageActivationAdvanceResponse {
+	outcome: "activating" | "active";
+	processedCollections: number;
+	activation: MediaUsageActivationStatus;
+}
+
 export type MediaUsageCollectionDeletionState = "pending" | "retry" | "leased" | "failed";
 export type MediaUsageCollectionDeletionPhase =
 	| "fence"
@@ -811,16 +860,27 @@ export class EmDashClient {
 		mimeType?: string;
 		limit?: number;
 		cursor?: string;
+		page?: number;
 		includeUsage?: boolean;
-	}): Promise<ListResult<MediaItem>> {
+		folderId?: string | null;
+	}): Promise<ListResult<MediaItem> & { totalCount?: number }> {
 		const params = new URLSearchParams();
 		if (options?.mimeType) params.set("mimeType", options.mimeType);
 		if (options?.limit) params.set("limit", String(options.limit));
 		if (options?.cursor) params.set("cursor", options.cursor);
+		if (options?.page !== undefined) params.set("page", String(options.page));
 		if (options?.includeUsage === true) params.set("includeUsage", "1");
+		if (options?.folderId === null) {
+			params.set("folderId", "unfiled");
+		} else if (options?.folderId !== undefined) {
+			params.set("folderId", options.folderId);
+		}
 
 		const qs = params.toString();
-		return this.request<ListResult<MediaItem>>("GET", `/media${qs ? `?${qs}` : ""}`);
+		return this.request<ListResult<MediaItem> & { totalCount?: number }>(
+			"GET",
+			`/media${qs ? `?${qs}` : ""}`,
+		);
 	}
 
 	/** Get a single media item */
@@ -836,6 +896,58 @@ export class EmDashClient {
 		return data.item;
 	}
 
+	/** List media folders */
+	async mediaFolderList(
+		options: { limit?: number; cursor?: string; q?: string } = {},
+	): Promise<ListResult<MediaFolder>> {
+		const params = new URLSearchParams();
+		if (options.limit !== undefined) params.set("limit", String(options.limit));
+		if (options.cursor !== undefined) params.set("cursor", options.cursor);
+		if (options.q !== undefined) params.set("q", options.q);
+		const qs = params.toString();
+		return this.request<ListResult<MediaFolder>>("GET", `/media/folders${qs ? `?${qs}` : ""}`);
+	}
+
+	/** Get one media folder */
+	async mediaFolderGet(id: string): Promise<MediaFolder> {
+		const data = await this.request<{ item: MediaFolder }>(
+			"GET",
+			`/media/folders/${encodeURIComponent(id)}`,
+		);
+		return data.item;
+	}
+
+	/** Create a media folder */
+	async mediaFolderCreate(name: string): Promise<MediaFolder> {
+		const data = await this.request<{ item: MediaFolder }>("POST", "/media/folders", { name });
+		return data.item;
+	}
+
+	/** Rename a media folder */
+	async mediaFolderUpdate(id: string, name: string): Promise<MediaFolder> {
+		const data = await this.request<{ item: MediaFolder }>(
+			"PUT",
+			`/media/folders/${encodeURIComponent(id)}`,
+			{ name },
+		);
+		return data.item;
+	}
+
+	/** Delete a media folder */
+	async mediaFolderDelete(id: string): Promise<void> {
+		await this.request<unknown>("DELETE", `/media/folders/${encodeURIComponent(id)}`);
+	}
+
+	/** Assign media to a folder, or return it to the Main library */
+	async mediaSetFolder(id: string, folderId: string | null): Promise<MediaFolderAssignment> {
+		const data = await this.request<{ item: MediaFolderAssignment }>(
+			"PUT",
+			`/media/${encodeURIComponent(id)}`,
+			{ folderId },
+		);
+		return { id: data.item.id, folderId: data.item.folderId };
+	}
+
 	/** Get entry-grouped usage details for a media item */
 	async mediaGetUsage(
 		id: string,
@@ -894,6 +1006,32 @@ export class EmDashClient {
 		return this.request<MediaUsageRepairResponse>("POST", "/admin/media-usage/repair", input);
 	}
 
+	/** Read aggregate Media Usage indexing progress */
+	async mediaGetUsageProgress(): Promise<MediaUsageProgress> {
+		return this.request<MediaUsageProgress>("GET", "/admin/media-usage/progress");
+	}
+
+	/** Advance exactly one Media Usage maintenance step */
+	async mediaAdvanceUsageProgress(): Promise<MediaUsageProgressAdvanceResponse> {
+		return this.request<MediaUsageProgressAdvanceResponse>("POST", "/admin/media-usage/progress");
+	}
+
+	/** Read the redacted controlled-activation status */
+	async mediaGetUsageActivation(): Promise<MediaUsageActivationStatus> {
+		return this.request<MediaUsageActivationStatus>("GET", "/admin/media-usage/activation");
+	}
+
+	/** Advance exactly one controlled-activation batch */
+	async mediaAdvanceUsageActivation(
+		input: MediaUsageActivationAdvanceInput,
+	): Promise<MediaUsageActivationAdvanceResponse> {
+		return this.request<MediaUsageActivationAdvanceResponse>(
+			"POST",
+			"/admin/media-usage/activation",
+			input,
+		);
+	}
+
 	/** List a bounded page of durable media usage entry work */
 	async mediaListUsageWork(
 		options: MediaUsageWorkListOptions,

package/src/client/transport.ts

@@ -186,6 +186,10 @@ export function refreshInterceptor(options: {
 	}
 
 	return async (request, next) => {
+		// A request body can only be read once; clone before sending so the
+		// 401 retry has an unconsumed request to rebuild from.
+		const retryTemplate = request.body ? request.clone() : request;
+
 		const response = await next(request);
 
 		if (response.status === 401) {
@@ -199,9 +203,9 @@ export function refreshInterceptor(options: {
 			const newToken = await refreshing;
 			if (newToken) {
 				// Retry with new token
-				const headers = new Headers(request.headers);
+				const headers = new Headers(retryTemplate.headers);
 				headers.set("Authorization", `Bearer ${newToken}`);
-				return next(new Request(request, { headers }));
+				return next(new Request(retryTemplate, { headers }));
 			}
 		}
 

package/src/components/EmDashImage.astro

@@ -15,12 +15,17 @@
  * <!-- With overrides -->
  * <Image image={post.data.featured_image} class="hero" />
  * ```
+ *
+ * When the image value carries a `darkVariant`, both images are rendered and
+ * CSS shows the one matching the page's color scheme. See the dark mode guide
+ * for the `<html>` class convention and how to override the selectors.
  */
-import type { MediaValue } from "../fields/types.js";
+import type { ImageValue, MediaValue } from "../fields/types.js";
 import type { HTMLAttributes } from "astro/types";
 import { Image as AstroImage, getImage } from "astro:assets";
 import type { ImageEmbed } from "../media/types.js";
 import { getMediaProvider } from "../media/provider-loader.js";
+import { normalizeLegacyExternalMediaValue } from "../media/normalize.js";
 import { buildRenderMediaUrl } from "../media/url.js";
 import {
 	buildResponsiveImage,
@@ -28,13 +33,19 @@ import {
 	RESPONSIVE_BREAKPOINTS,
 } from "../media/responsive.js";
 import { getPublicOrigin } from "../api/public-url.js";
+import { focalPointToObjectPosition } from "../media/focal-point.js";
 
 interface Props extends Omit<
 	HTMLAttributes<"img">,
 	"src" | "width" | "height"
 > {
 	/** Image value from content field or media library */
-	image: MediaValue | string | undefined | null;
+	image: ImageValue | string | undefined | null;
+	/**
+	 * Image shown in a dark color scheme. Defaults to `image.darkVariant`;
+	 * pass it explicitly when the dark image comes from another field.
+	 */
+	darkVariant?: MediaValue | string | undefined | null;
 	/** Override alt text (uses image.alt by default) */
 	alt?: string;
 	/** Override width (uses image.width by default) */
@@ -49,12 +60,14 @@ interface Props extends Omit<
 
 const {
 	image,
+	darkVariant,
 	alt,
 	width,
 	height,
 	priority,
 	placeholder = true,
 	class: className,
+	id,
 	...attrs
 } = Astro.props;
 
@@ -66,7 +79,7 @@ function normalizeImage(
 	if (typeof img === "string") {
 		return { id: "", src: img };
 	}
-	return img;
+	return normalizeLegacyExternalMediaValue(img);
 }
 
 /**
@@ -96,22 +109,31 @@ function generateSrcset(
 		.join(", ");
 }
 
-const img = normalizeImage(image);
+interface ResolvedImage {
+	src: string;
+	srcset?: string;
+	sizes?: string;
+	astroImageSrc: string;
+	width?: number;
+	height?: number;
+	generatedStyle: string;
+}
 
-// Determine final dimensions (props override image metadata)
-const finalWidth = width ?? img?.width;
-const finalHeight = height ?? img?.height;
-const finalAlt = alt ?? img?.alt ?? "";
-const aspectRatio =
-	finalWidth && finalHeight ? finalWidth / finalHeight : undefined;
+/**
+ * Resolve the source URL, srcset, dimensions, and LQIP style for one media
+ * value. Props override the value's own dimensions.
+ */
+async function resolveImage(img: MediaValue): Promise<ResolvedImage> {
+	const finalWidth = width ?? img.width;
+	const finalHeight = height ?? img.height;
+	const aspectRatio =
+		finalWidth && finalHeight ? finalWidth / finalHeight : undefined;
 
-// Get the image source URL and srcset
-let src = "";
-let srcset: string | undefined;
-let sizes: string | undefined;
-let astroImageSrc = "";
+	let src = "";
+	let srcset: string | undefined;
+	let sizes: string | undefined;
+	let astroImageSrc = "";
 
-if (img) {
 	const providerId = img.provider ?? "local";
 
 	if (providerId === "local" || img.src) {
@@ -170,56 +192,119 @@ if (img) {
 			src = buildLocalImageUrl(img);
 		}
 	}
+
+	// Build placeholder background style. Prefer the first-class MediaValue fields;
+	// fall back to `meta` for snapshots stored before LQIP was promoted off `meta`.
+	const blurhash = img.blurhash ?? (img.meta?.blurhash as string | undefined);
+	const dominantColor =
+		img.dominantColor ?? (img.meta?.dominantColor as string | undefined);
+
+	let placeholderStyle = "";
+	if (placeholder && blurhash) {
+		const { blurhashToImageCssString } = await import("@unpic/placeholder");
+		placeholderStyle = blurhashToImageCssString(blurhash);
+	} else if (placeholder && dominantColor) {
+		placeholderStyle = `background-color: ${dominantColor};`;
+	}
+
+	// The focal point travels with the media value, so the dark variant gets
+	// its own object-position rather than inheriting the light image's.
+	const objectPosition = focalPointToObjectPosition(img.focalX, img.focalY);
+	const generatedStyle = [
+		placeholderStyle,
+		objectPosition ? `object-position: ${objectPosition};` : "",
+	]
+		.filter(Boolean)
+		.join(" ");
+
+	return {
+		src,
+		srcset,
+		sizes,
+		astroImageSrc,
+		width: finalWidth,
+		height: finalHeight,
+		generatedStyle,
+	};
 }
 
-// Build placeholder background style. Prefer the first-class MediaValue fields;
-// fall back to `meta` for snapshots stored before LQIP was promoted off `meta`.
-const blurhash =
-	img?.blurhash ?? (img?.meta?.blurhash as string | undefined);
-const dominantColor =
-	img?.dominantColor ?? (img?.meta?.dominantColor as string | undefined);
-
-let placeholderStyle = "";
-if (placeholder && blurhash) {
-	const { blurhashToImageCssString } = await import("@unpic/placeholder");
-	placeholderStyle = blurhashToImageCssString(blurhash);
-} else if (placeholder && dominantColor) {
-	placeholderStyle = `background-color: ${dominantColor};`;
+const img = normalizeImage(image);
+const darkSource =
+	darkVariant ?? (typeof image === "object" ? image?.darkVariant : undefined);
+const dark = img ? normalizeImage(darkSource) : null;
+const finalAlt = alt ?? img?.alt ?? "";
+
+const resolved = img ? await resolveImage(img) : null;
+const resolvedDark = dark ? await resolveImage(dark) : null;
+
+function imgProps(
+	r: ResolvedImage,
+	variantClass: string | undefined,
+	elementId: string | null | undefined
+): Record<string, unknown> {
+	return {
+		id: elementId,
+		src: r.src,
+		srcset: r.srcset,
+		sizes: r.sizes,
+		width: r.width,
+		height: r.height,
+		alt: finalAlt,
+		loading: priority ? "eager" : "lazy",
+		fetchpriority: priority ? "high" : undefined,
+		decoding: "async",
+		style: r.generatedStyle || undefined,
+		class: ["emdash-image-media", variantClass, className].filter(Boolean).join(" "),
+		...attrs,
+	};
 }
 
-const imgProps: Record<string, unknown> = {
-	src,
-	srcset,
-	sizes,
-	width: finalWidth,
-	height: finalHeight,
-	alt: finalAlt,
-	loading: priority ? "eager" : "lazy",
-	fetchpriority: priority ? "high" : undefined,
-	decoding: "async",
-	style: placeholderStyle || undefined,
-	class: ["emdash-image-media", className].filter(Boolean).join(" "),
-	...attrs,
-};
+const lightClass = resolvedDark ? "emdash-image--light" : undefined;
+// Both variants render into the same document, so a caller-supplied `id` would
+// otherwise appear on two elements.
+const darkId = id ? `${id}--dark` : undefined;
+const astroClass = (variantClass: string | undefined) =>
+	[variantClass, className].filter(Boolean).join(" ") || undefined;
 ---
 
 {
-	img && astroImageSrc ? (
+	resolved && resolved.astroImageSrc ? (
+		<AstroImage
+			id={id}
+			src={resolved.astroImageSrc}
+			alt={finalAlt}
+			width={resolved.width}
+			height={resolved.height}
+			priority={priority}
+			layout="constrained"
+			loading={priority ? "eager" : "lazy"}
+			decoding="async"
+			class={astroClass(lightClass)}
+			style={resolved.generatedStyle || undefined}
+			{...attrs}
+		/>
+	) : resolved && resolved.src ? (
+		<img {...imgProps(resolved, lightClass, id)} />
+	) : null
+}
+{
+	resolvedDark && resolvedDark.astroImageSrc ? (
 		<AstroImage
-			src={astroImageSrc}
+			id={darkId}
+			src={resolvedDark.astroImageSrc}
 			alt={finalAlt}
-			width={finalWidth}
-			height={finalHeight}
+			width={resolvedDark.width}
+			height={resolvedDark.height}
 			priority={priority}
 			layout="constrained"
 			loading={priority ? "eager" : "lazy"}
 			decoding="async"
-			class={className}
-			style={placeholderStyle || undefined}
+			class={astroClass("emdash-image--dark")}
+			style={resolvedDark.generatedStyle || undefined}
 			{...attrs}
 		/>
-	) : img && src ? (
-		<img {...imgProps} />
+	) : resolvedDark && resolvedDark.src ? (
+		<img {...imgProps(resolvedDark, "emdash-image--dark", darkId)} />
 	) : null
 }
 
@@ -229,3 +314,23 @@ const imgProps: Record<string, unknown> = {
 		height: auto;
 	}
 </style>
+
+<style is:global>
+	/* A `dark` or `light` class on <html> wins over the system preference. */
+	:where(:root.dark) .emdash-image--light {
+		display: none;
+	}
+	:where(:root.light) .emdash-image--dark {
+		display: none;
+	}
+	@media (prefers-color-scheme: dark) {
+		:where(:root:not(.light)) .emdash-image--light {
+			display: none;
+		}
+	}
+	@media (prefers-color-scheme: light) {
+		:where(:root:not(.dark)) .emdash-image--dark {
+			display: none;
+		}
+	}
+</style>

package/src/components/EmDashMedia.astro

@@ -20,6 +20,7 @@ import type { MediaValue } from "../fields/types.js";
 import type { EmbedResult, EmbedOptions } from "../media/types.js";
 import type { HTMLAttributes } from "astro/types";
 import { getMediaProvider } from "../media/provider-loader.js";
+import { normalizeLegacyExternalMediaValue } from "../media/normalize.js";
 
 interface Props extends Omit<HTMLAttributes<"img" | "video" | "audio">, "src" | "width" | "height"> {
 	/** Media value from content field */
@@ -42,7 +43,7 @@ function normalizeValue(val: MediaValue | string | undefined | null): MediaValue
 	if (typeof val === "string") {
 		return { id: "", src: val, provider: "local" };
 	}
-	return val;
+	return normalizeLegacyExternalMediaValue(val);
 }
 
 const media = normalizeValue(value);

package/src/components/Gallery.astro

@@ -13,6 +13,7 @@ import { getMediaProvider } from "../media/provider-loader.js";
 import { buildRenderMediaUrl } from "../media/url.js";
 import { toAbsoluteMediaUrl, RESPONSIVE_BREAKPOINTS } from "../media/responsive.js";
 import { getPublicOrigin } from "../api/public-url.js";
+import { focalPointToObjectPosition } from "../media/focal-point.js";
 
 export interface Props {
 	node: {
@@ -31,6 +32,8 @@ export interface Props {
 			caption?: string;
 			width?: number;
 			height?: number;
+			focalX?: number;
+			focalY?: number;
 			/** LQIP blurhash placeholder (images only) */
 			blurhash?: string;
 			/** LQIP dominant-color placeholder, as a CSS color (images only) */
@@ -72,6 +75,7 @@ const resolvedImages = await Promise.all(
 	images.map(async (image) => {
 		const { asset, alt = "", width, height } = image;
 		const aspectRatio = width && height ? width / height : undefined;
+		const objectPosition = focalPointToObjectPosition(image.focalX, image.focalY);
 
 		let src = "";
 		let srcset: string | undefined;
@@ -145,6 +149,7 @@ const resolvedImages = await Promise.all(
 			sizes,
 			astroImageSrc,
 			placeholderStyle,
+			objectPosition,
 		};
 	}),
 );
@@ -161,6 +166,7 @@ const resolvedImages = await Promise.all(
 						width={image.width!}
 						height={image.height!}
 						layout="constrained"
+						style={image.objectPosition ? `object-position: ${image.objectPosition};` : undefined}
 					/>
 				) : (
 					<img
@@ -172,6 +178,7 @@ const resolvedImages = await Promise.all(
 						height={image.height}
 						loading="lazy"
 						decoding="async"
+						style={image.objectPosition ? `object-position: ${image.objectPosition};` : undefined}
 					/>
 				)}
 				{image.caption && <figcaption>{image.caption}</figcaption>}