@phis/ui 0.1.0

package/components/media/focal-rect.d.ts

@@ -0,0 +1,38 @@
+export type MediaFocalRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare function clampRectValue(value: number): number;
+export declare function normalizeMediaFocalRect(value: unknown): MediaFocalRect | null;
+export declare function createDefaultFocalRect(): MediaFocalRect;
+export declare function focalRectToPercent(value: number): string;
+export declare function focalRectToMetaValue(value: MediaFocalRect | null): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+export declare function resolveFocalRectCoverCropBox(sourceWidth: number, sourceHeight: number, targetWidth: number, targetHeight: number, focalRect: MediaFocalRect | null): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export declare function resolveFocalRectCoverImageStyle(sourceWidth: number | null | undefined, sourceHeight: number | null | undefined, targetWidth: number, targetHeight: number, focalRect: MediaFocalRect | null): {
+    position: "absolute";
+    left: string;
+    top: string;
+    width: string;
+    height: string;
+    maxWidth: string;
+    maxHeight: string;
+} | null;
+export declare function resolveContainedImageBox(frameWidth: number, frameHeight: number, sourceWidth: number, sourceHeight: number): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+} | null;
+export declare function resolveFocalRectObjectPosition(objectPosition: string | null | undefined, focalRect: MediaFocalRect | null): string;

package/components/media/focal-rect.js

@@ -0,0 +1,123 @@
+export function clampRectValue(value) {
+    return Math.min(Math.max(value, 0), 1);
+}
+export function normalizeMediaFocalRect(value) {
+    if (value === null || value === undefined || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const x = typeof record.x === "number" && Number.isFinite(record.x) ? clampRectValue(record.x) : null;
+    const y = typeof record.y === "number" && Number.isFinite(record.y) ? clampRectValue(record.y) : null;
+    const width = typeof record.width === "number" && Number.isFinite(record.width) && record.width > 0
+        ? clampRectValue(record.width)
+        : null;
+    const height = typeof record.height === "number" && Number.isFinite(record.height) && record.height > 0
+        ? clampRectValue(record.height)
+        : null;
+    if (x === null || y === null || width === null || height === null) {
+        return null;
+    }
+    const normalizedWidth = Math.min(width, 1 - x);
+    const normalizedHeight = Math.min(height, 1 - y);
+    if (normalizedWidth <= 0 || normalizedHeight <= 0) {
+        return null;
+    }
+    return {
+        x,
+        y,
+        width: normalizedWidth,
+        height: normalizedHeight,
+    };
+}
+export function createDefaultFocalRect() {
+    return {
+        x: 0.25,
+        y: 0.25,
+        width: 0.5,
+        height: 0.5,
+    };
+}
+export function focalRectToPercent(value) {
+    return `${Math.round(value * 1000) / 10}%`;
+}
+export function focalRectToMetaValue(value) {
+    return value ? { x: value.x, y: value.y, width: value.width, height: value.height } : null;
+}
+export function resolveFocalRectCoverCropBox(sourceWidth, sourceHeight, targetWidth, targetHeight, focalRect) {
+    const targetRatio = targetWidth / targetHeight;
+    let cropWidth = sourceWidth;
+    let cropHeight = Math.round(cropWidth / targetRatio);
+    if (cropHeight > sourceHeight) {
+        cropHeight = sourceHeight;
+        cropWidth = Math.round(cropHeight * targetRatio);
+    }
+    cropWidth = Math.max(1, Math.min(sourceWidth, cropWidth));
+    cropHeight = Math.max(1, Math.min(sourceHeight, cropHeight));
+    let left = Math.round((sourceWidth - cropWidth) / 2);
+    let top = Math.round((sourceHeight - cropHeight) / 2);
+    if (focalRect) {
+        const focalLeft = focalRect.x * sourceWidth;
+        const focalTop = focalRect.y * sourceHeight;
+        const focalRight = (focalRect.x + focalRect.width) * sourceWidth;
+        const focalBottom = (focalRect.y + focalRect.height) * sourceHeight;
+        const focalCenterX = (focalLeft + focalRight) / 2;
+        const focalCenterY = (focalTop + focalBottom) / 2;
+        left = Math.round(focalCenterX - cropWidth / 2);
+        top = Math.round(focalCenterY - cropHeight / 2);
+        if (cropWidth >= focalRight - focalLeft) {
+            left = Math.min(Math.max(left, Math.ceil(focalRight - cropWidth)), Math.floor(focalLeft));
+        }
+        if (cropHeight >= focalBottom - focalTop) {
+            top = Math.min(Math.max(top, Math.ceil(focalBottom - cropHeight)), Math.floor(focalTop));
+        }
+    }
+    left = Math.min(Math.max(left, 0), Math.max(0, sourceWidth - cropWidth));
+    top = Math.min(Math.max(top, 0), Math.max(0, sourceHeight - cropHeight));
+    return {
+        left,
+        top,
+        width: cropWidth,
+        height: cropHeight,
+    };
+}
+export function resolveFocalRectCoverImageStyle(sourceWidth, sourceHeight, targetWidth, targetHeight, focalRect) {
+    if (!sourceWidth || !sourceHeight) {
+        return null;
+    }
+    const cropBox = resolveFocalRectCoverCropBox(sourceWidth, sourceHeight, targetWidth, targetHeight, focalRect);
+    return {
+        position: "absolute",
+        left: `${(-cropBox.left / cropBox.width) * 100}%`,
+        top: `${(-cropBox.top / cropBox.height) * 100}%`,
+        width: `${(sourceWidth / cropBox.width) * 100}%`,
+        height: `${(sourceHeight / cropBox.height) * 100}%`,
+        maxWidth: "none",
+        maxHeight: "none",
+    };
+}
+export function resolveContainedImageBox(frameWidth, frameHeight, sourceWidth, sourceHeight) {
+    if (frameWidth <= 0 || frameHeight <= 0 || sourceWidth <= 0 || sourceHeight <= 0) {
+        return null;
+    }
+    const scale = Math.min(frameWidth / sourceWidth, frameHeight / sourceHeight);
+    const width = sourceWidth * scale;
+    const height = sourceHeight * scale;
+    return {
+        left: (frameWidth - width) / 2,
+        top: (frameHeight - height) / 2,
+        width,
+        height,
+    };
+}
+export function resolveFocalRectObjectPosition(objectPosition, focalRect) {
+    const normalizedObjectPosition = objectPosition?.trim();
+    if (normalizedObjectPosition) {
+        return normalizedObjectPosition;
+    }
+    if (!focalRect) {
+        return "center";
+    }
+    const centerX = (focalRect.x + focalRect.width / 2) * 100;
+    const centerY = (focalRect.y + focalRect.height / 2) * 100;
+    return `${Math.round(centerX * 10) / 10}% ${Math.round(centerY * 10) / 10}%`;
+}

package/components/media/image-presentation.d.ts

@@ -0,0 +1,91 @@
+import { type PhiImageAssetVariantSpec } from "../../constants/media";
+import { resolveFocalRectCoverImageStyle, type MediaFocalRect } from "./focal-rect";
+/**
+ * An original Asset and a generated variant are different presentation inputs, and every surface
+ * that draws an image has to make the same distinction. This module owns that decision once so the
+ * Image Widget, the Card Widget, and Background bases cannot drift apart:
+ *
+ * - The ORIGINAL carries the raw pixels. Authoring owns how it meets its box, so the configured
+ *   `fit` and `objectPosition` apply, and where no explicit position exists the focal rectangle
+ *   supplies one.
+ * - A GENERATED VARIANT is a finished server crop. The server already consumed the focal rectangle,
+ *   so applying it a second time would shift an image that is already framed. The variant spec
+ *   decides `fit`, the position is always centered, and a box with a different aspect ratio gets
+ *   centered cover overflow rather than a stretch.
+ *
+ * The single exception is an unsaved focal edit: Authoring may set `simulateVariantCrop` to draw the
+ * original and reproduce the server crop locally, because the stored variant still shows the old
+ * framing. After the save the invalidated variant takes over again under its new variant version.
+ */
+export type PhiImagePresentationFit = "cover" | "contain" | "fill";
+export type PhiImagePresentationKind = "original" | "generated-variant";
+/**
+ * Render-time projection of the Asset a config binds by id. It carries server-owned delivery facts
+ * that must never be persisted as authoring intent: the delivery revision, the variant version a focal
+ * change bumps, the focal rectangle itself, and the intrinsic size. Server renders and Builder drafts
+ * both fill it from the bulk reference resolver, Authoring fills it from the Picker, and
+ * `builder-persistence` strips it before saving -- the same lifecycle `resolvedContent` has on
+ * Content Widgets.
+ */
+export type PhiImageDeliveryProjection = {
+    deliveryUrl?: string | null;
+    deliveryRevision?: number | null;
+    variantVersion?: number | null;
+    focalRect?: unknown;
+    width?: number | null;
+    height?: number | null;
+    /** A few hundred bytes of the picture, blurred, for a surface to show while the original loads. */
+    blurDataUrl?: string | null;
+};
+export type PhiImagePresentationInput = {
+    sourceKind?: "asset" | "url" | null;
+    assetId?: number | null;
+    variantKey?: unknown;
+    variantVersion?: number | null;
+    /**
+     * Server-owned revision of the delivered original. Both this and `variantVersion` exist to defeat a
+     * cached URL rather than to select content: the server always serves the newest bytes. Measured on
+     * 2026-08-20, a focal change bumps `variantVersion` and leaves `deliveryRevision` untouched, so the
+     * variant URL is what moves while the original keeps its revision.
+     */
+    deliveryRevision?: number | null;
+    /** Delivery URL of the original bytes. An Asset source renders nothing without it. */
+    originalUrl?: string | null;
+    /** Delivery URL for a non-Asset source. */
+    sourceUrl?: string | null;
+    focalRect?: unknown;
+    /** Authoring intent. Consumed by the original only. */
+    fit?: PhiImagePresentationFit | null;
+    /** Authoring intent. Consumed by the original only. */
+    objectPosition?: string | null;
+    /** Intrinsic size of the original, when known. */
+    sourceWidth?: number | null;
+    sourceHeight?: number | null;
+    /** Unsaved focal edit: draw the original and simulate the server crop. */
+    simulateVariantCrop?: boolean;
+};
+export type PhiImagePresentation = {
+    kind: PhiImagePresentationKind;
+    url: string | null;
+    fit: PhiImagePresentationFit;
+    objectPosition: string;
+    /** Intended presentation box: the variant spec when one is configured, else the original size. */
+    width: number | null;
+    height: number | null;
+    focalRect: MediaFocalRect | null;
+    variantSpec: PhiImageAssetVariantSpec | null;
+    /**
+     * Absolutely positioned style that reproduces the server crop from the original. Non-null only
+     * while `simulateVariantCrop` is in effect AND the variant actually crops -- a `contain` variant
+     * letterboxes the whole image instead, so there is nothing to reproduce and `fit` carries it.
+     * It belongs on the image inside a clipped wrapper.
+     */
+    simulatedCropStyle: ReturnType<typeof resolveFocalRectCoverImageStyle>;
+};
+/**
+ * Removes every render-time Asset projection from a config before it is persisted. Shape-driven so
+ * a Background nested in a new container cannot smuggle a delivery revision into stored content,
+ * where it would go stale the moment the focal rectangle changes.
+ */
+export declare function stripPhiResolvedAssetProjections<T>(value: T): T;
+export declare function resolvePhiImagePresentation(input: PhiImagePresentationInput): PhiImagePresentation;

package/components/media/image-presentation.js

@@ -0,0 +1,63 @@
+import { buildPhiImageAssetVariantDeliveryUrl, normalizePhiImageAssetVariantKey, resolvePhiImageAssetVariantSpec, } from "../../constants/media";
+import { normalizeMediaFocalRect, resolveFocalRectCoverImageStyle, resolveFocalRectObjectPosition, } from "./focal-rect";
+/**
+ * Removes every render-time Asset projection from a config before it is persisted. Shape-driven so
+ * a Background nested in a new container cannot smuggle a delivery revision into stored content,
+ * where it would go stale the moment the focal rectangle changes.
+ */
+export function stripPhiResolvedAssetProjections(value) {
+    if (Array.isArray(value)) {
+        return value.map(stripPhiResolvedAssetProjections);
+    }
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const stripped = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (key === "resolvedAsset")
+            continue;
+        stripped[key] = stripPhiResolvedAssetProjections(entry);
+    }
+    return stripped;
+}
+export function resolvePhiImagePresentation(input) {
+    const isAssetSource = input.sourceKind === "asset";
+    const variantKey = isAssetSource ? normalizePhiImageAssetVariantKey(input.variantKey) : null;
+    const variantSpec = variantKey == null ? null : resolvePhiImageAssetVariantSpec(variantKey);
+    const focalRect = normalizeMediaFocalRect(input.focalRect) ?? null;
+    const simulate = input.simulateVariantCrop === true && variantSpec != null;
+    const kind = variantSpec != null && !simulate ? "generated-variant" : "original";
+    const originalUrl = input.originalUrl?.trim() || null;
+    const variantUrl = kind === "generated-variant" && input.assetId != null
+        ? buildPhiImageAssetVariantDeliveryUrl(input.assetId, variantKey, input.variantVersion, input.deliveryRevision)
+        : null;
+    const url = isAssetSource
+        ? originalUrl == null
+            ? null
+            : variantUrl ?? originalUrl
+        : input.sourceUrl?.trim() || null;
+    // A simulated crop places the image absolutely, so a position would have nothing left to steer, and a
+    // simulated `contain` shows the whole image, where a focal position would only misalign the letterbox.
+    const objectPosition = kind === "generated-variant" || (simulate && variantSpec.fit !== "cover")
+        ? "center"
+        : simulate
+            ? resolveFocalRectObjectPosition(undefined, focalRect)
+            : resolveFocalRectObjectPosition(input.objectPosition, focalRect);
+    return {
+        kind,
+        url,
+        // A simulation draws the original into the variant's box, so it answers to the variant's fit and
+        // not to the authored one -- otherwise a `contain` variant would preview as a crop.
+        fit: variantSpec != null && (kind === "generated-variant" || simulate)
+            ? variantSpec.fit
+            : input.fit ?? "cover",
+        objectPosition,
+        width: variantSpec?.width ?? input.sourceWidth ?? null,
+        height: variantSpec?.height ?? input.sourceHeight ?? null,
+        focalRect,
+        variantSpec,
+        simulatedCropStyle: simulate && variantSpec.fit === "cover"
+            ? resolveFocalRectCoverImageStyle(input.sourceWidth, input.sourceHeight, variantSpec.width, variantSpec.height, focalRect)
+            : null,
+    };
+}

package/components/media/label-sets/media.d.ts

@@ -0,0 +1,4 @@
+import "server-only";
+import { type PhiGlobalTranslatorOptions } from "../../../gateway/tr";
+import { type PhiAssetWidgetLabels } from "../media-widget-labels";
+export declare function getPhiMediaWidgetLabels(options: PhiGlobalTranslatorOptions): Promise<PhiAssetWidgetLabels>;

package/components/media/label-sets/media.js

@@ -0,0 +1,217 @@
+import "server-only";
+import { definePhiLabelSet, definePhiMessageLabel, getPhiLabelSet } from "../../../gateway/label-set";
+import { PHI_TR_CTX_WEB_UI_LABEL } from "../../../gateway/tr";
+import { PHI_MEDIA_WIDGET_DEFAULT_LABELS, } from "../media-widget-labels";
+const PHI_MEDIA_WIDGET_LABEL_SET = definePhiLabelSet({
+    key: "widget:media",
+    ctx: PHI_TR_CTX_WEB_UI_LABEL,
+    labels: {
+        tool_search_placeholder: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.searchPlaceholder,
+        tool_folder_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.folderLabel,
+        tool_create_folder_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.createFolderLabel,
+        tool_flags_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.flagsLabel,
+        tool_flag_placeholder: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.flagPlaceholder,
+        tool_upload_toggle_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.uploadToggleLabel,
+        tool_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.kindLabel,
+        tool_reset_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.resetLabel,
+        tool_reload_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.reloadLabel,
+        tool_assets_template: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.assetsTemplate,
+        tool_image_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.imageKindLabel,
+        tool_video_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.videoKindLabel,
+        tool_audio_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.audioKindLabel,
+        tool_pdf_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.pdfKindLabel,
+        tool_markdown_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.markdownKindLabel,
+        tool_document_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.documentKindLabel,
+        tool_archive_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.archiveKindLabel,
+        tool_font_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.fontKindLabel,
+        tool_binary_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.binaryKindLabel,
+        tool_other_kind_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.tool.otherKindLabel,
+        upload_drop_title: PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.dropTitle,
+        upload_drop_hint: PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.dropHint,
+        upload_upload_toggle_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.uploadToggleLabel,
+        upload_retry_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.retryLabel,
+        upload_delete_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.deleteLabel,
+        upload_done_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.doneLabel,
+        upload_failed_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.failedLabel,
+        upload_asset_exists_label: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.assetExistsLabel),
+        upload_delete_success_template: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.deleteSuccessTemplate),
+        upload_upload_success_template: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.uploadSuccessTemplate),
+        upload_upload_failed_text: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.uploadFailedText),
+        upload_storage_unreachable_text: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.uploadStorageUnreachableText),
+        upload_delete_failed_text: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.upload.deleteFailedText),
+        grid_empty_description: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.grid.emptyDescription),
+        grid_delete_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.grid.deleteLabel,
+        grid_delete_success_template: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.grid.deleteSuccessTemplate),
+        grid_delete_failed_text: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.grid.deleteFailedText),
+        inspector_inspector_title: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.inspectorTitle,
+        inspector_preview_title: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.previewTitle,
+        inspector_metadata_title: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.metadataTitle,
+        inspector_variants_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.variantsLabel,
+        inspector_original_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.originalVariantLabel,
+        inspector_thumbnail_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.thumbnailVariantLabel,
+        inspector_preview_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.previewVariantLabel,
+        inspector_banner_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.bannerVariantLabel,
+        inspector_header_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.headerVariantLabel,
+        inspector_card_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.cardVariantLabel,
+        inspector_hero_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.heroVariantLabel,
+        inspector_avatar_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.avatarVariantLabel,
+        inspector_logo_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.logoVariantLabel,
+        inspector_landscape_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.landscapeVariantLabel,
+        inspector_portrait_variant_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.portraitVariantLabel,
+        inspector_storage_key_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.storageKeyLabel,
+        inspector_public_url_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.publicUrlLabel,
+        inspector_content_type_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.contentTypeLabel,
+        inspector_original_name_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.originalNameLabel,
+        inspector_restricted_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.restrictedLabel,
+        inspector_copy_label_template: PHI_MEDIA_WIDGET_DEFAULT_LABELS.inspector.copyLabelTemplate,
+        editor_title_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.titleLabel,
+        editor_alt_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.altLabel,
+        editor_folder_path_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.folderPathLabel,
+        editor_folder_path_placeholder: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.folderPathPlaceholder,
+        editor_folder_path_help: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.folderPathHelp),
+        editor_create_folder_title: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.createFolderTitle,
+        editor_folder_name_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.folderNameLabel,
+        editor_folder_name_placeholder: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.folderNamePlaceholder,
+        editor_folder_name_required: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.folderNameRequired),
+        editor_parent_folder_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.parentFolderLabel,
+        editor_top_level_folder_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.topLevelFolderLabel,
+        editor_flags_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.flagsLabel,
+        editor_focal_rect_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.focalRectLabel,
+        editor_focal_rect_button_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.focalRectButtonLabel,
+        editor_focal_rect_save_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.focalRectSaveLabel,
+        editor_focal_rect_reset_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.focalRectResetLabel,
+        editor_focal_rect_clear_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.focalRectClearLabel,
+        editor_focal_rect_help_label: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.focalRectHelpLabel),
+        editor_save_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.saveLabel,
+        editor_saving_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.savingLabel,
+        editor_save_success_text: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.saveSuccessText),
+        editor_save_failed_text: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.saveFailedText),
+        editor_featured_flag_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.featuredFlagLabel,
+        editor_locked_flag_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.lockedFlagLabel,
+        editor_mask_flag_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.maskFlagLabel,
+        editor_background_flag_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.editor.backgroundFlagLabel,
+        picker_trigger_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.picker.triggerLabel,
+        picker_popover_title: PHI_MEDIA_WIDGET_DEFAULT_LABELS.picker.popoverTitle,
+        picker_selected_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.picker.selectedLabel,
+        picker_empty_description: definePhiMessageLabel(PHI_MEDIA_WIDGET_DEFAULT_LABELS.picker.emptyDescription),
+        picker_clear_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.picker.clearLabel,
+        picker_tile_size_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.picker.tileSizeLabel,
+        space_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.space.label,
+        space_site_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.space.site,
+        space_user_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.space.user,
+        space_group_label: PHI_MEDIA_WIDGET_DEFAULT_LABELS.space.group,
+    },
+});
+export async function getPhiMediaWidgetLabels(options) {
+    const labels = await getPhiLabelSet(options, PHI_MEDIA_WIDGET_LABEL_SET);
+    return {
+        tool: {
+            searchPlaceholder: labels.tool_search_placeholder,
+            folderLabel: labels.tool_folder_label,
+            createFolderLabel: labels.tool_create_folder_label,
+            flagsLabel: labels.tool_flags_label,
+            flagPlaceholder: labels.tool_flag_placeholder,
+            uploadToggleLabel: labels.tool_upload_toggle_label,
+            kindLabel: labels.tool_kind_label,
+            resetLabel: labels.tool_reset_label,
+            reloadLabel: labels.tool_reload_label,
+            assetsTemplate: labels.tool_assets_template,
+            imageKindLabel: labels.tool_image_kind_label,
+            videoKindLabel: labels.tool_video_kind_label,
+            audioKindLabel: labels.tool_audio_kind_label,
+            pdfKindLabel: labels.tool_pdf_kind_label,
+            markdownKindLabel: labels.tool_markdown_kind_label,
+            documentKindLabel: labels.tool_document_kind_label,
+            archiveKindLabel: labels.tool_archive_kind_label,
+            fontKindLabel: labels.tool_font_kind_label,
+            binaryKindLabel: labels.tool_binary_kind_label,
+            otherKindLabel: labels.tool_other_kind_label,
+        },
+        upload: {
+            dropTitle: labels.upload_drop_title,
+            dropHint: labels.upload_drop_hint,
+            uploadToggleLabel: labels.upload_upload_toggle_label,
+            retryLabel: labels.upload_retry_label,
+            deleteLabel: labels.upload_delete_label,
+            doneLabel: labels.upload_done_label,
+            failedLabel: labels.upload_failed_label,
+            assetExistsLabel: labels.upload_asset_exists_label,
+            deleteSuccessTemplate: labels.upload_delete_success_template,
+            uploadSuccessTemplate: labels.upload_upload_success_template,
+            uploadFailedText: labels.upload_upload_failed_text,
+            uploadStorageUnreachableText: labels.upload_storage_unreachable_text,
+            deleteFailedText: labels.upload_delete_failed_text,
+        },
+        grid: {
+            emptyDescription: labels.grid_empty_description,
+            deleteLabel: labels.grid_delete_label,
+            deleteSuccessTemplate: labels.grid_delete_success_template,
+            deleteFailedText: labels.grid_delete_failed_text,
+        },
+        inspector: {
+            inspectorTitle: labels.inspector_inspector_title,
+            previewTitle: labels.inspector_preview_title,
+            metadataTitle: labels.inspector_metadata_title,
+            variantsLabel: labels.inspector_variants_label,
+            originalVariantLabel: labels.inspector_original_variant_label,
+            thumbnailVariantLabel: labels.inspector_thumbnail_variant_label,
+            previewVariantLabel: labels.inspector_preview_variant_label,
+            bannerVariantLabel: labels.inspector_banner_variant_label,
+            headerVariantLabel: labels.inspector_header_variant_label,
+            cardVariantLabel: labels.inspector_card_variant_label,
+            heroVariantLabel: labels.inspector_hero_variant_label,
+            avatarVariantLabel: labels.inspector_avatar_variant_label,
+            logoVariantLabel: labels.inspector_logo_variant_label,
+            landscapeVariantLabel: labels.inspector_landscape_variant_label,
+            portraitVariantLabel: labels.inspector_portrait_variant_label,
+            storageKeyLabel: labels.inspector_storage_key_label,
+            publicUrlLabel: labels.inspector_public_url_label,
+            contentTypeLabel: labels.inspector_content_type_label,
+            originalNameLabel: labels.inspector_original_name_label,
+            restrictedLabel: labels.inspector_restricted_label,
+            copyLabelTemplate: labels.inspector_copy_label_template,
+        },
+        editor: {
+            titleLabel: labels.editor_title_label,
+            altLabel: labels.editor_alt_label,
+            folderPathLabel: labels.editor_folder_path_label,
+            folderPathPlaceholder: labels.editor_folder_path_placeholder,
+            folderPathHelp: labels.editor_folder_path_help,
+            createFolderTitle: labels.editor_create_folder_title,
+            folderNameLabel: labels.editor_folder_name_label,
+            folderNamePlaceholder: labels.editor_folder_name_placeholder,
+            folderNameRequired: labels.editor_folder_name_required,
+            parentFolderLabel: labels.editor_parent_folder_label,
+            topLevelFolderLabel: labels.editor_top_level_folder_label,
+            flagsLabel: labels.editor_flags_label,
+            focalRectLabel: labels.editor_focal_rect_label,
+            focalRectButtonLabel: labels.editor_focal_rect_button_label,
+            focalRectSaveLabel: labels.editor_focal_rect_save_label,
+            focalRectResetLabel: labels.editor_focal_rect_reset_label,
+            focalRectClearLabel: labels.editor_focal_rect_clear_label,
+            focalRectHelpLabel: labels.editor_focal_rect_help_label,
+            saveLabel: labels.editor_save_label,
+            savingLabel: labels.editor_saving_label,
+            saveSuccessText: labels.editor_save_success_text,
+            saveFailedText: labels.editor_save_failed_text,
+            featuredFlagLabel: labels.editor_featured_flag_label,
+            lockedFlagLabel: labels.editor_locked_flag_label,
+            maskFlagLabel: labels.editor_mask_flag_label,
+            backgroundFlagLabel: labels.editor_background_flag_label,
+        },
+        picker: {
+            triggerLabel: labels.picker_trigger_label,
+            popoverTitle: labels.picker_popover_title,
+            selectedLabel: labels.picker_selected_label,
+            emptyDescription: labels.picker_empty_description,
+            clearLabel: labels.picker_clear_label,
+            tileSizeLabel: labels.picker_tile_size_label,
+        },
+        space: {
+            label: labels.space_label,
+            site: labels.space_site_label,
+            user: labels.space_user_label,
+            group: labels.space_group_label,
+        },
+    };
+}

package/components/media/media-settings-forms.d.ts

@@ -0,0 +1,22 @@
+export declare const PHI_MEDIA_SETTINGS_FORM_IDS: {
+    readonly general: `${string}/forms/${string}`;
+};
+export declare const PHI_MEDIA_SETTINGS_FORM_HANDLER_KEYS: {
+    readonly general: "site.admin.media-settings";
+};
+export declare const PHI_MEDIA_SETTINGS_RUNTIME_MODULE_FORM: import("../forms/form-registry").PhiRuntimeModuleFormDefinition;
+export declare const PHI_MEDIA_SETTINGS_FORM_HANDLER_PROVIDER_DESCRIPTOR: {
+    key: `${string}/${string}`;
+    ownerModuleId: "@phis/ui/modules/asset";
+    title: string;
+    phase: "submit";
+    handlerKey: "site.admin.media-settings";
+    category: "site";
+    transport: "relay";
+    method: "PATCH";
+    endpointKey: null;
+    upstreamPath: string;
+    csrfPath: null;
+    requiresCsrf: false;
+    credentialPolicy: "site-session";
+};