@phis/ui 0.2.0 → 0.3.0

package/components/media/background-asset-projection.js

@@ -2,9 +2,9 @@ import { isPhiRecord } from "../../helpers/is-record";
 /**
  * Backgrounds bind an Asset by id, but drawing one needs facts the config cannot hold: the delivery
  * revision, the variant version a focal change bumps, the focal rectangle, and the intrinsic size.
- * Content Widgets
- * already get theirs from a projection (`resolvedContent`); this is the same move for the Region,
- * Layout, and Overlay configs a page or a Builder draft renders.
+ * A Content Widget's own pictures come from its own projection (`resolvedContent`); this is the same
+ * move for the Region, Layout, and Overlay configs a page or a Builder draft renders, and for the
+ * Surface of every Content Widget.
  *
  * Collecting and applying are pure and live here so the live render and the Builder share one rule.
  * Only fetching differs: the server resolves in bulk through the reference gateway, the Builder reads
@@ -12,10 +12,12 @@ import { isPhiRecord } from "../../helpers/is-record";
  * the shell Backgrounds render without a revision until a browser check caught it.
  *
  * The walk is shape-driven rather than key-driven on purpose. Background bases sit under `background`,
- * `backgroundConfig`, `rootNodeBackground`, and slot-level keys, and a new container would otherwise
- * silently render a stale crop until someone remembered to extend a key list.
+ * `backgroundConfig`, `surface.background`, and slot-level keys, and a new container would otherwise
+ * silently render a stale crop until someone remembered to extend a key list. A Content Widget is the
+ * exception: only its `surface` is walked, because the rest of its config is the Widget's own and its
+ * own pictures are already projected by `resolvedContent`.
  */
-export const PHI_BACKGROUND_RESOLVED_ASSET_KEY = "resolvedAsset";
+const PHI_BACKGROUND_RESOLVED_ASSET_KEY = "resolvedAsset";
 /** An Asset-bound image background: the only shape that needs a delivery projection. */
 function readBackgroundAssetId(value) {
     if (value.kind !== "image" || value.sourceKind !== "asset") {
@@ -54,6 +56,9 @@ export function collectPhiBackgroundAssetIds(trees) {
         for (const node of [...tree.regions, ...tree.layoutNodes, ...tree.overlays]) {
             collectFrom(node.config, assetIds);
         }
+        for (const widget of tree.contentWidgets) {
+            collectFrom(widget.config?.surface, assetIds);
+        }
     }
     return [...assetIds];
 }
@@ -94,10 +99,14 @@ export function applyPhiBackgroundAssetProjection(tree, assets) {
         ...node,
         config: projectInto(node.config, assets),
     });
+    const withSurfaceProjection = (widget) => widget.config?.surface == null
+        ? widget
+        : { ...widget, config: { ...widget.config, surface: projectInto(widget.config.surface, assets) } };
     return {
         ...tree,
         regions: tree.regions.map(withProjection),
         layoutNodes: tree.layoutNodes.map(withProjection),
         overlays: tree.overlays.map(withProjection),
+        contentWidgets: tree.contentWidgets.map(withSurfaceProjection),
     };
 }

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

@@ -4,7 +4,6 @@ export type MediaFocalRect = {
     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;
@@ -36,3 +35,23 @@ export declare function resolveContainedImageBox(frameWidth: number, frameHeight
     height: number;
 } | null;
 export declare function resolveFocalRectObjectPosition(objectPosition: string | null | undefined, focalRect: MediaFocalRect | null): string;
+/**
+ * Where to stand a picture in a box of a known proportion so that its focal rectangle is seen whole.
+ *
+ * `resolveFocalRectObjectPosition` aligns the rectangle's centre with the same point of the box, which
+ * is the best a box of unknown proportion allows and wrong for one that is known: a head in the top
+ * quarter of a portrait, shown in a wide box, had its crown cut off although the box had room for all
+ * of it. With the proportion the cover crop is known exactly (`resolveFocalRectCoverCropBox`, the same
+ * crop the server would cut), and `object-position` is the share of the overflow that puts that crop
+ * in view. The axis that does not overflow is centred, as it would be anyway.
+ */
+export declare function resolveFocalRectObjectPositionForFrame(sourceWidth: number | null | undefined, sourceHeight: number | null | undefined, frameAspectRatio: number | null | undefined, focalRect: MediaFocalRect | null): string | null;
+/**
+ * The focal rectangle as it stands inside a cover crop of the original -- a generated variant.
+ *
+ * A variant is the original cropped around its focal rectangle to the variant's proportion. Shown in a
+ * box of yet another proportion, it is cropped once more, and that second crop has to keep the same
+ * focus: centred, it would cut away what the first crop was made to keep. This is the rectangle to
+ * position it by, in the variant's own coordinates.
+ */
+export declare function resolveFocalRectInCoverCrop(sourceWidth: number, sourceHeight: number, targetWidth: number, targetHeight: number, focalRect: MediaFocalRect): MediaFocalRect;

package/components/media/focal-rect.js

@@ -1,8 +1,9 @@
-export function clampRectValue(value) {
+import { isPhiRecord } from "../../helpers/is-record";
+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)) {
+    if (!isPhiRecord(value)) {
         return null;
     }
     const record = value;
@@ -121,3 +122,37 @@ export function resolveFocalRectObjectPosition(objectPosition, focalRect) {
     const centerY = (focalRect.y + focalRect.height / 2) * 100;
     return `${Math.round(centerX * 10) / 10}% ${Math.round(centerY * 10) / 10}%`;
 }
+/**
+ * Where to stand a picture in a box of a known proportion so that its focal rectangle is seen whole.
+ *
+ * `resolveFocalRectObjectPosition` aligns the rectangle's centre with the same point of the box, which
+ * is the best a box of unknown proportion allows and wrong for one that is known: a head in the top
+ * quarter of a portrait, shown in a wide box, had its crown cut off although the box had room for all
+ * of it. With the proportion the cover crop is known exactly (`resolveFocalRectCoverCropBox`, the same
+ * crop the server would cut), and `object-position` is the share of the overflow that puts that crop
+ * in view. The axis that does not overflow is centred, as it would be anyway.
+ */
+export function resolveFocalRectObjectPositionForFrame(sourceWidth, sourceHeight, frameAspectRatio, focalRect) {
+    if (!sourceWidth || !sourceHeight || !frameAspectRatio || !Number.isFinite(frameAspectRatio) || frameAspectRatio <= 0) {
+        return null;
+    }
+    const crop = resolveFocalRectCoverCropBox(sourceWidth, sourceHeight, frameAspectRatio * 1000, 1000, focalRect);
+    const share = (offset, overflow) => overflow > 0.5 ? Math.round(clampRectValue(offset / overflow) * 1000) / 10 : 50;
+    return `${share(crop.left, sourceWidth - crop.width)}% ${share(crop.top, sourceHeight - crop.height)}%`;
+}
+/**
+ * The focal rectangle as it stands inside a cover crop of the original -- a generated variant.
+ *
+ * A variant is the original cropped around its focal rectangle to the variant's proportion. Shown in a
+ * box of yet another proportion, it is cropped once more, and that second crop has to keep the same
+ * focus: centred, it would cut away what the first crop was made to keep. This is the rectangle to
+ * position it by, in the variant's own coordinates.
+ */
+export function resolveFocalRectInCoverCrop(sourceWidth, sourceHeight, targetWidth, targetHeight, focalRect) {
+    const crop = resolveFocalRectCoverCropBox(sourceWidth, sourceHeight, targetWidth, targetHeight, focalRect);
+    const left = clampRectValue((focalRect.x * sourceWidth - crop.left) / crop.width);
+    const top = clampRectValue((focalRect.y * sourceHeight - crop.top) / crop.height);
+    const right = clampRectValue(((focalRect.x + focalRect.width) * sourceWidth - crop.left) / crop.width);
+    const bottom = clampRectValue(((focalRect.y + focalRect.height) * sourceHeight - crop.top) / crop.height);
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}

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

@@ -10,8 +10,10 @@ import { resolveFocalRectCoverImageStyle, type MediaFocalRect } from "./focal-re
  *   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.
+ *   decides `fit`. A box of the variant's proportion shows it whole; a box of another proportion crops
+ *   it again, around where the focal rectangle stands inside the variant -- the original's focal
+ *   rectangle carried into the variant's coordinates, not applied to them a second time. Without the
+ *   original's size or a focal rectangle, around the centre.
  *
  * 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
@@ -63,7 +65,15 @@ export type PhiImagePresentationInput = {
     sourceHeight?: number | null;
     /** Unsaved focal edit: draw the original and simulate the server crop. */
     simulateVariantCrop?: boolean;
+    /**
+     * The proportion (width over height) of the box the picture is drawn in, where the caller knows it --
+     * a Gallery frame with an aspect ratio. With it a cover crop is positioned so the focal rectangle is
+     * seen whole; without it the rectangle's centre is the best that can be done.
+     */
+    frameAspectRatio?: number | null;
 };
+/** A CSS `aspect-ratio` value -- `16 / 9`, `4/3`, `1.5` -- as width over height, or `null` for none. */
+export declare function readPhiAspectRatio(value: string | null | undefined): number | null;
 export type PhiImagePresentation = {
     kind: PhiImagePresentationKind;
     url: string | null;

package/components/media/image-presentation.js

@@ -1,5 +1,17 @@
 import { buildPhiImageAssetVariantDeliveryUrl, normalizePhiImageAssetVariantKey, resolvePhiImageAssetVariantSpec, } from "../../constants/media";
-import { normalizeMediaFocalRect, resolveFocalRectCoverImageStyle, resolveFocalRectObjectPosition, } from "./focal-rect";
+import { normalizeMediaFocalRect, resolveFocalRectCoverImageStyle, resolveFocalRectInCoverCrop, resolveFocalRectObjectPosition, resolveFocalRectObjectPositionForFrame, } from "./focal-rect";
+/** A CSS `aspect-ratio` value -- `16 / 9`, `4/3`, `1.5` -- as width over height, or `null` for none. */
+export function readPhiAspectRatio(value) {
+    const text = value?.trim();
+    if (!text)
+        return null;
+    const parts = text.split("/").map((part) => Number.parseFloat(part.trim()));
+    const width = parts[0] ?? Number.NaN;
+    const height = parts.length > 1 ? parts[1] ?? Number.NaN : 1;
+    if (parts.length > 2 || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0)
+        return null;
+    return width / height;
+}
 /**
  * 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,
@@ -38,11 +50,26 @@ export function resolvePhiImagePresentation(input) {
         : 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);
+    const frameAspectRatio = input.frameAspectRatio ?? null;
+    const objectPosition = kind === "generated-variant"
+        ? variantSpec.fit === "cover" && focalRect && input.sourceWidth && input.sourceHeight
+            ? (() => {
+                const rectInVariant = resolveFocalRectInCoverCrop(input.sourceWidth, input.sourceHeight, variantSpec.width, variantSpec.height, focalRect);
+                return resolveFocalRectObjectPositionForFrame(variantSpec.width, variantSpec.height, frameAspectRatio, rectInVariant)
+                    ?? resolveFocalRectObjectPosition(undefined, rectInVariant);
+            })()
+            : "center"
+        : simulate && variantSpec.fit !== "cover"
+            ? "center"
+            : simulate
+                ? resolveFocalRectObjectPosition(undefined, focalRect)
+                : input.objectPosition?.trim()
+                    ? resolveFocalRectObjectPosition(input.objectPosition, focalRect)
+                    // A box of known proportion shows the focal rectangle whole; one of unknown proportion its centre.
+                    : ((input.fit ?? "cover") === "cover"
+                        ? resolveFocalRectObjectPositionForFrame(input.sourceWidth, input.sourceHeight, frameAspectRatio, focalRect)
+                        : null)
+                        ?? resolveFocalRectObjectPosition(undefined, focalRect);
     return {
         kind,
         url,

package/components/media/media-folder-options.d.ts

@@ -9,6 +9,8 @@ export declare function buildPhiMediaFolderOptions(folders: PhiMediaAssetFolder[
     }>[];
 }[];
 export declare function buildPhiMediaFolderPathById(folders: PhiMediaAssetFolder[], folderId: number | null): number[];
+/** The names of the folders from the root down to `folderId`, read like `buildPhiMediaFolderPathById`. */
+export declare function buildPhiMediaFolderNamesById(folders: PhiMediaAssetFolder[], folderId: number | null): string[];
 export declare function buildPhiMediaFolderValueById(folders: PhiMediaAssetFolder[], folderId: number | null): string;
 export declare function buildPhiMediaFolderCascaderOptions(folders: PhiMediaAssetFolder[]): {
     value: string;

package/components/media/media-folder-options.js

@@ -43,6 +43,11 @@ export function buildPhiMediaFolderPathById(folders, folderId) {
     }
     return path;
 }
+/** The names of the folders from the root down to `folderId`, read like `buildPhiMediaFolderPathById`. */
+export function buildPhiMediaFolderNamesById(folders, folderId) {
+    const byId = new Map(folders.map((folder) => [folder.id, folder]));
+    return buildPhiMediaFolderPathById(folders, folderId).map((id) => byId.get(id).name);
+}
 export function buildPhiMediaFolderValueById(folders, folderId) {
     const path = buildPhiMediaFolderPathById(folders, folderId);
     return path.length > 0 ? `/${path.join("/")}` : "/";

package/components/media/media-space-selection.d.ts

@@ -1,37 +1,10 @@
 import type { PhiSignalRuntimePartitionKind } from "../runtime/runtime-signal-partition";
 import type { PhiMediaSpaceOption } from "../../types/media";
-/**
- * Which surface may name a Media Space, and which is pinned to the Site Space.
- *
- * A Space is a place a person works in, not a place content is authored from. Someone in `app` works
- * inside their own Space and the Spaces of their groups, so they choose. Everything an author builds is
- * Site content, so Builder and Editor stay on the Site Space -- otherwise a published Page could end up
- * pointing at an Asset that only one group may read. `public` never picks at all.
- *
- * The partition kind is what makes this reliable rather than advisory: a Builder canvas renders the
- * Area it edits, so its `area` really is `app` while it previews the App. Only a live Area partition is
- * someone actually working in that Area; a `canvas` partition is always authoring.
- *
- * This is an interface rule, not the authorization boundary. The control plane resolves every requested
- * Space against the actor's own authority and answers `space_forbidden` regardless of what asked.
- */
-export declare const PHI_MEDIA_SPACE_SELECTING_AREAS: readonly ["app"];
 export declare function canPhiSurfaceSelectMediaSpace(input: {
     partitionKind: PhiSignalRuntimePartitionKind | null;
     area: string | null;
 }): boolean;
 export declare function usePhiMediaSpaceSelectionAllowed(): boolean;
-/**
- * The label a Space carries in the selector.
- *
- * A group Space is named after its group, because that is what a member recognizes. The Site Space and
- * a personal Space have no name of their own and fall back to what they are.
- */
-export declare function readPhiMediaSpaceOptionLabel(space: PhiMediaSpaceOption, labels: {
-    site: string;
-    user: string;
-    group: string;
-}): string;
 export declare function buildPhiMediaSpaceOptions(spaces: readonly PhiMediaSpaceOption[], labels: {
     site: string;
     user: string;

package/components/media/media-space-selection.js

@@ -15,7 +15,7 @@ import { usePhiSignalRuntimePartition } from "../runtime/runtime-signal-partitio
  * This is an interface rule, not the authorization boundary. The control plane resolves every requested
  * Space against the actor's own authority and answers `space_forbidden` regardless of what asked.
  */
-export const PHI_MEDIA_SPACE_SELECTING_AREAS = ["app"];
+const PHI_MEDIA_SPACE_SELECTING_AREAS = ["app"];
 export function canPhiSurfaceSelectMediaSpace(input) {
     if (input.partitionKind !== "area") {
         return false;
@@ -35,7 +35,7 @@ export function usePhiMediaSpaceSelectionAllowed() {
  * A group Space is named after its group, because that is what a member recognizes. The Site Space and
  * a personal Space have no name of their own and fall back to what they are.
  */
-export function readPhiMediaSpaceOptionLabel(space, labels) {
+function readPhiMediaSpaceOptionLabel(space, labels) {
     if (space.kind === "group")
         return space.name?.trim() || labels.group;
     return space.kind === "user" ? labels.user : labels.site;

package/components/media/media-upload-flow.d.ts

@@ -107,11 +107,12 @@ export type PhiMediaUploadProgressHandler = (progress: number) => void;
  * uses the Add-on's root. Making it a parameter is what lets the acceptance, the progress, the refusal
  * and the labels stay shared instead of being written twice with the second one drifting.
  */
-export type PhiMediaUploadSessionRunner = (file: File, onProgress?: PhiMediaUploadProgressHandler, options?: PhiMediaUploadInitOptions) => Promise<{
+export type PhiMediaUploadSessionRunner = (file: File, onProgress?: PhiMediaUploadProgressHandler, options?: PhiMediaUploadInitOptions, signal?: AbortSignal) => Promise<{
     asset: {
         id: number;
     };
 }>;
+export declare function isPhiMediaUploadCancelled(error: unknown): boolean;
 export type PhiMediaUploadSessionResult = {
     asset: PhiImagePreviewApiRecord;
     token: string;
@@ -163,13 +164,6 @@ export declare const PHI_MEDIA_UPLOAD_FAILURE_REASONS: {
     readonly ClientError: "client_error";
 };
 export type PhiMediaUploadFailureReason = (typeof PHI_MEDIA_UPLOAD_FAILURE_REASONS)[keyof typeof PHI_MEDIA_UPLOAD_FAILURE_REASONS];
-/**
- * Tells the Server a body will not arrive.
- *
- * Deliberately quiet: it is a courtesy to the operator's log, not a step the upload depends on, so a
- * failure to report must not replace the failure being reported.
- */
-export declare function reportPhiMediaUploadFailure(reportUrl: string, reason: PhiMediaUploadFailureReason, detail?: string | null): Promise<void>;
 /**
  * Whether a plan says enough to be carried out.
  *
@@ -212,14 +206,21 @@ export declare function resolvePhiMediaUploadInitOptions(input: {
     configPresentationFlags?: number | null;
     activeSpaceAddress?: string | null;
 }): PhiMediaUploadInitOptions;
-export declare function initPhiMediaUploadSession(file: File, options?: PhiMediaUploadInitOptions): Promise<PhiMediaUploadInitSession>;
+export declare function initPhiMediaUploadSession(file: File, options?: PhiMediaUploadInitOptions, signal?: AbortSignal): Promise<PhiMediaUploadInitSession>;
 export declare function uploadPhiMediaUploadBody(plan: PhiMediaUploadPlan, file: File, onProgress?: PhiMediaUploadProgressHandler, 
 /** Parts an earlier attempt delivered, where this session was taken over rather than opened. */
-stored?: readonly PhiMediaUploadStoredPart[]): Promise<PhiMediaUploadUploadResponse>;
-export declare function finalizePhiMediaUploadSession(finalizeUrl: string, completion?: unknown): Promise<{
-    asset: PhiImagePreviewApiRecord;
-}>;
-export declare function runPhiMediaUploadSession(file: File, onProgress?: PhiMediaUploadProgressHandler, options?: PhiMediaUploadInitOptions): Promise<PhiMediaUploadSessionResult>;
+stored?: readonly PhiMediaUploadStoredPart[], 
+/** Stops the body where it is; what is in flight is aborted and the call throws `cancelled`. */
+signal?: AbortSignal): Promise<PhiMediaUploadUploadResponse>;
+/**
+ * One file through Core's own upload routes.
+ *
+ * `signal` stops it up to the moment finalize is sent: an init in flight is aborted, a body in flight is
+ * aborted and reported `cancelled`, so the Server clears up the reservation and whatever arrived. Once
+ * finalize is sent it is not stopped -- the Server is already turning the body into an Asset, and aborting
+ * the request would only hide the answer. A caller that stopped it ignores what comes back.
+ */
+export declare function runPhiMediaUploadSession(file: File, onProgress?: PhiMediaUploadProgressHandler, options?: PhiMediaUploadInitOptions, signal?: AbortSignal): Promise<PhiMediaUploadSessionResult>;
 /**
  * A place an Add-on's route made for a file, as `assets:v1` answered it.
  *
@@ -255,5 +256,7 @@ export declare function runPhiAddonAssetUpload<TAsset>(input: {
     onProgress?: PhiMediaUploadProgressHandler;
     /** Where the Add-on's Client says a body will not arrive. Core's own route when absent. */
     reportUrl?: string;
+    /** Stops the body up to finalize, as in `runPhiMediaUploadSession`. */
+    signal?: AbortSignal;
 }): Promise<TAsset>;
 export {};