@phis/ui 0.1.0

package/components/media/phi-media-upload.js

@@ -0,0 +1,148 @@
+"use client";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { PhiMediaKind, resolvePhiMediaKindFromContentType } from "../../constants/media";
+import { PhiMediaUploadError, runPhiMediaUploadSession, } from "./media-upload-flow";
+/**
+ * Text for a surface that has no label set of its own.
+ *
+ * Not a substitute for one: it exists so a surface without translations still says something an ordinary
+ * person can act on, rather than showing whatever string the server happened to send. Leaking a control
+ * plane message into an interface is what these replace.
+ */
+export const PHI_MEDIA_UPLOAD_DEFAULT_LABELS = {
+    errorGeneric: "The upload did not work.",
+    errorNetwork: "The site could not be reached.",
+    errorTooLarge: "That file is too large.",
+    errorDuplicate: "That file is already here.",
+    errorTypeNotAllowed: "That file type is not accepted here.",
+    errorQuotaExceeded: "There is no room left in this space.",
+    errorSpaceUnavailable: "That space is not available.",
+    errorStorageUnreachable: "The file storage could not be reached.",
+};
+/** The `accept` attribute a file dialog should carry, derived rather than written out by each caller. */
+export function resolvePhiMediaUploadAccept(acceptance) {
+    const types = acceptance?.contentTypes ?? [];
+    const kinds = acceptance?.kinds ?? [];
+    const fromKinds = kinds.flatMap((kind) => kind === PhiMediaKind.Image ? ["image/*"]
+        : kind === PhiMediaKind.Video ? ["video/*"]
+            : kind === PhiMediaKind.Audio ? ["audio/*"]
+                : kind === PhiMediaKind.Pdf ? ["application/pdf"]
+                    : kind === PhiMediaKind.Markdown ? ["text/markdown"]
+                        /*
+                         * Fonts carry their suffixes as well as their family, because a file dialog is the one
+                         * place where the type is the operating system's opinion: plenty of desktops hand a
+                         * `.woff2` over with no type at all, and a dialog narrowed to `font/*` alone would grey
+                         * out exactly the files somebody opened it for.
+                         */
+                        : kind === PhiMediaKind.Font
+                            ? ["font/*", ".woff2", ".woff", ".ttf", ".otf", ".ttc"]
+                            : []);
+    const merged = [...new Set([...types, ...fromKinds])];
+    return merged.length > 0 ? merged.join(",") : "*/*";
+}
+function matchesContentType(contentType, allowed) {
+    if (allowed.length === 0)
+        return true;
+    const normalized = contentType.trim().toLowerCase().split(";")[0].trim();
+    const slash = normalized.indexOf("/");
+    const family = slash > 0 ? `${normalized.slice(0, slash)}/*` : null;
+    return allowed.some((entry) => {
+        const candidate = entry.trim().toLowerCase();
+        return candidate === normalized || (family != null && candidate === family);
+    });
+}
+/** Why this file cannot be sent, or `null` when it can. */
+export function readPhiMediaUploadRejection(file, acceptance, labels) {
+    if (acceptance?.maxBytes != null && file.size > acceptance.maxBytes) {
+        return labels.errorTooLarge;
+    }
+    if (acceptance?.contentTypes?.length && !matchesContentType(file.type, acceptance.contentTypes)) {
+        return labels.errorTypeNotAllowed;
+    }
+    /*
+     * A file the browser could not name is not a file this can refuse.
+     *
+     * The kind is derived from the type the browser states, and for a font it often states nothing --
+     * the check would then read `other` and turn away the very file the dialog was opened for. Refusing
+     * on the absence of evidence is worse than sending it: the server reads the bytes, and that is the
+     * answer that binds anyway.
+     */
+    if (acceptance?.kinds?.length && file.type.trim()
+        && !acceptance.kinds.includes(resolvePhiMediaKindFromContentType(file.type))) {
+        return labels.errorTypeNotAllowed;
+    }
+    return null;
+}
+/**
+ * One reading of every refusal the upload path can produce.
+ *
+ * Each surface used to know a different subset -- one knew about duplicates, another about size and
+ * an unavailable Space -- so the same refusal read differently depending on where a person happened to
+ * be standing. The codes come from the control plane; anything unrecognized falls to the generic text
+ * rather than leaking a server message into an interface.
+ */
+export function readPhiMediaUploadErrorMessage(error, labels) {
+    const code = error instanceof PhiMediaUploadError
+        ? error.code
+        : error?.code;
+    switch (code) {
+        case "media_asset_exists": return labels.errorDuplicate;
+        case "media_asset_too_large": return labels.errorTooLarge;
+        case "content_type_not_allowed": return labels.errorTypeNotAllowed;
+        case "media_quota_exceeded": return labels.errorQuotaExceeded;
+        case "space_kind_unavailable":
+        case "space_forbidden":
+        case "space_not_found": return labels.errorSpaceUnavailable;
+        // A presigned plan is delivered past the Site: reaching the Site says nothing about reaching the
+        // Provider, so this is deliberately not the same reading as a network failure.
+        case "storage_unreachable":
+        case "storage_rejected": return labels.errorStorageUnreachable;
+        default: break;
+    }
+    // A TypeError from fetch is the browser saying it never reached the site at all.
+    return error instanceof TypeError ? labels.errorNetwork : labels.errorGeneric;
+}
+/**
+ * The shared half of every upload surface: accept, transport, progress, refusal.
+ *
+ * What it deliberately does not own is what happens afterwards -- appending a tile, binding an avatar,
+ * replacing a preview. That is the only part that differs between the surfaces, so it stays with them
+ * and arrives through `onUploaded`.
+ */
+export function usePhiMediaUpload(input) {
+    const { labels, acceptance, initOptions, onUploaded, onRejected } = input;
+    const runSession = input.runSession ?? runPhiMediaUploadSession;
+    const [items, setItems] = useState([]);
+    const sequence = useRef(0);
+    const accept = useMemo(() => resolvePhiMediaUploadAccept(acceptance), [acceptance]);
+    const patch = useCallback((localId, next) => {
+        setItems((current) => current.map((item) => item.localId === localId ? { ...item, ...next } : item));
+    }, []);
+    const upload = useCallback(async (file) => {
+        const rejection = readPhiMediaUploadRejection(file, acceptance, labels);
+        if (rejection) {
+            onRejected?.(rejection, file);
+            return null;
+        }
+        sequence.current += 1;
+        const localId = `upload-${sequence.current}`;
+        setItems((current) => [
+            { localId, file, progress: 0, status: "uploading", error: null, assetId: null },
+            ...current,
+        ]);
+        try {
+            const { asset } = await runSession(file, (progress) => patch(localId, { progress }), initOptions);
+            patch(localId, { progress: 100, status: "done", assetId: asset.id });
+            await onUploaded?.(asset, file);
+            return asset;
+        }
+        catch (error) {
+            const message = readPhiMediaUploadErrorMessage(error, labels);
+            patch(localId, { progress: 100, status: "error", error: message });
+            onRejected?.(message, file);
+            return null;
+        }
+    }, [acceptance, initOptions, labels, onRejected, onUploaded, patch, runSession]);
+    const reset = useCallback(() => setItems([]), []);
+    return { accept, items, upload, reset };
+}

package/components/media/phi-site-font-assets.d.ts

@@ -0,0 +1,17 @@
+import type { PhiFontMetrics } from "../../types/media";
+export type PhiSiteFontAssetOption = {
+    assetId: number;
+    /** What a Theme writes into the slot. */
+    value: string;
+    /** The family the file states, or the best name there is for it. */
+    label: string;
+    /** Where the file is and what it says about itself, for a surface that wants to show the face. */
+    deliveryUrl: string;
+    deliveryRevision: number;
+    contentType: string;
+    metrics: PhiFontMetrics | null;
+};
+export declare function usePhiSiteFontAssets(enabled?: boolean): {
+    options: readonly PhiSiteFontAssetOption[];
+    loading: boolean;
+};

package/components/media/phi-site-font-assets.js

@@ -0,0 +1,81 @@
+"use client";
+import { useEffect, useMemo, useState } from "react";
+import { PhiMediaKind } from "../../constants/media";
+import { createPhiAssetUri } from "../../types/references";
+import { usePhiCollectionProvider } from "../widgets/client/shared/phi-collection-provider";
+import { PHI_ASSET_COLLECTION_DATA_SOURCE } from "./asset-collection-runtime";
+/**
+ * The typefaces a Site owns, as something a font slot can be set to.
+ *
+ * A slot holds either a family name -- one the font catalogue declares -- or a `phis:asset` reference
+ * to a file in the Media library. This is the second list, and it is short by nature: a Site has a
+ * handful of typefaces, not a library of them, so it is read once and whole rather than paged.
+ *
+ * The name shown is the one the file gave itself, read out of the font at upload. Only where the file
+ * named no family does the Asset's own title stand in -- a typeface is known by its family, and the
+ * file name it happened to be uploaded under is the last resort.
+ */
+/** Enough for any Site's own lettering; a ceiling rather than a page size. */
+const PHI_SITE_FONT_ASSET_LIMIT = 100;
+function readFontAssetMetrics(asset) {
+    const meta = asset.meta?.font;
+    if (!meta || typeof meta !== "object" || Array.isArray(meta))
+        return null;
+    const record = meta;
+    // The management tile carries `meta` as stored; only a shape with its unit grid is worth drawing from.
+    return typeof record.unitsPerEm === "number" && record.unitsPerEm > 0 ? record : null;
+}
+function readFontAssetLabel(asset) {
+    const family = readFontAssetMetrics(asset)?.familyName;
+    if (typeof family === "string" && family.trim())
+        return family.trim();
+    return asset.title?.trim() || asset.originalName.trim();
+}
+export function usePhiSiteFontAssets(enabled = true) {
+    const { provider } = usePhiCollectionProvider(PHI_ASSET_COLLECTION_DATA_SOURCE);
+    const [assets, setAssets] = useState([]);
+    const [loading, setLoading] = useState(false);
+    useEffect(() => {
+        if (!enabled || !provider)
+            return;
+        const abortController = new AbortController();
+        // The request is the external state this mirrors; loading starts with it, inside the same effect.
+        // eslint-disable-next-line react-hooks/set-state-in-effect
+        setLoading(true);
+        void provider.query({
+            resourceKey: PHI_ASSET_COLLECTION_DATA_SOURCE.resourceKey,
+            query: {
+                page: 1,
+                pageSize: PHI_SITE_FONT_ASSET_LIMIT,
+                sortKey: "created_at",
+                sortOrder: "descend",
+                filters: { kind: PhiMediaKind.Font },
+            },
+            signal: abortController.signal,
+        }).then((data) => {
+            if (abortController.signal.aborted)
+                return;
+            setAssets(data.items.filter((item) => Boolean(item)));
+        }).catch(() => {
+            // A library that cannot be read leaves the catalogue families, which is a usable list.
+            if (!abortController.signal.aborted)
+                setAssets([]);
+        }).finally(() => {
+            if (!abortController.signal.aborted)
+                setLoading(false);
+        });
+        return () => abortController.abort();
+    }, [enabled, provider]);
+    const options = useMemo(() => assets
+        .filter((asset) => asset.kind === PhiMediaKind.Font)
+        .map((asset) => ({
+        assetId: asset.id,
+        value: createPhiAssetUri(asset.id),
+        label: readFontAssetLabel(asset),
+        deliveryUrl: asset.deliveryUrl,
+        deliveryRevision: asset.deliveryRevision,
+        contentType: asset.contentType,
+        metrics: readFontAssetMetrics(asset),
+    })), [assets]);
+    return { options, loading };
+}

package/components/media/use-authoring-asset-details.d.ts

@@ -0,0 +1,8 @@
+import type { PhiMediaAsset } from "../../types/media";
+/**
+ * Authoring surfaces need the same Asset facts the server render has: the delivery revision that a
+ * focal change bumps, the focal rectangle itself, and the intrinsic size. The Picker store already
+ * holds a freshly reloaded tile after every metadata save, and the detail request adds the variant
+ * list, so both are merged here once instead of in each Widget editor.
+ */
+export declare function usePhiAuthoringAssetDetails(assetId: number | null | undefined): PhiMediaAsset | null;

package/components/media/use-authoring-asset-details.js

@@ -0,0 +1,61 @@
+"use client";
+import { useEffect, useMemo, useState } from "react";
+import { PHI_ASSET_CONTROLLER_STORE_KEY } from "./asset-controller-signals";
+import { usePhiImagePreviewStore } from "./phi-image-preview-store";
+/**
+ * Authoring surfaces need the same Asset facts the server render has: the delivery revision that a
+ * focal change bumps, the focal rectangle itself, and the intrinsic size. The Picker store already
+ * holds a freshly reloaded tile after every metadata save, and the detail request adds the variant
+ * list, so both are merged here once instead of in each Widget editor.
+ */
+export function usePhiAuthoringAssetDetails(assetId) {
+    const [assetDetails, setAssetDetails] = useState(null);
+    const previewState = usePhiImagePreviewStore(PHI_ASSET_CONTROLLER_STORE_KEY);
+    useEffect(() => {
+        if (assetId == null) {
+            return undefined;
+        }
+        const controller = new AbortController();
+        async function run() {
+            try {
+                const response = await fetch(`/api/site/media/${assetId}`, {
+                    method: "GET",
+                    headers: { Accept: "application/json" },
+                    cache: "no-store",
+                    signal: controller.signal,
+                });
+                const payload = (await response.json());
+                if (!controller.signal.aborted) {
+                    setAssetDetails(response.ok ? payload.asset ?? null : null);
+                }
+            }
+            catch (error) {
+                if (!controller.signal.aborted) {
+                    console.warn("Failed to load image asset variant details.", error);
+                }
+            }
+        }
+        void run();
+        return () => {
+            controller.abort();
+        };
+    }, [assetId]);
+    const currentAssetTile = previewState.selectedAsset?.id === assetId
+        ? previewState.selectedAsset
+        : previewState.assets.find((asset) => asset.id === assetId) ?? null;
+    return useMemo(() => {
+        const fetchedAsset = assetDetails?.id === assetId ? assetDetails : null;
+        if (!currentAssetTile)
+            return fetchedAsset;
+        // A stale variant list belongs to the previous variant version; dropping it is what makes an
+        // invalidated variant visible instead of the crop the Editor showed before the focal change.
+        const keepFetchedVariants = fetchedAsset?.variantVersion === currentAssetTile.variantVersion;
+        return {
+            ...currentAssetTile,
+            blurDataUrl: currentAssetTile.blurDataUrl ?? null,
+            meta: currentAssetTile.meta ?? null,
+            folder: fetchedAsset?.folder ?? null,
+            variants: keepFetchedVariants ? fetchedAsset?.variants ?? null : null,
+        };
+    }, [assetDetails, assetId, currentAssetTile]);
+}

package/components/menus/phi-account-menu.d.ts

@@ -0,0 +1,54 @@
+import type { ReactNode, Ref } from "react";
+import type { PhiNavItem } from "../shell/shell-types";
+export type PhiAccountMenuLabels = {
+    trigger: {
+        account: string;
+    };
+    guest: {
+        login: string;
+        register: string;
+    };
+    authenticated: {
+        profile: string;
+        settings: string;
+        logout: string;
+    };
+};
+export type PhiAccountMenuState = {
+    kind: "guest";
+    loginHref?: string;
+    onLogin?: () => void;
+    registerHref?: string;
+} | {
+    kind: "authenticated";
+    profileHref?: string;
+    settingsHref?: string;
+    logoutHref?: string;
+    displayName?: string;
+    onProfile?: () => void;
+    onLogout?: () => void;
+};
+export type PhiAccountMenuProps = {
+    labels: PhiAccountMenuLabels;
+    state: PhiAccountMenuState;
+    /**
+     * Entries Modules contributed to the `<area>:account` surface.
+     *
+     * They sit above the Area's own account entries and their divider, because a Module's entry is about
+     * the person -- their picture, their preferences -- while what follows is about the session. An entry
+     * with an `overlayInstanceId` opens something in place and gets `onOpenOverlay`; one with an `href`
+     * is an ordinary link.
+     */
+    contributedItems?: readonly PhiNavItem[];
+    onOpenOverlay?: (overlayInstanceId: string) => void;
+    avatarSrc?: string;
+    avatarAlt?: string;
+    icon?: ReactNode;
+    triggerRef?: Ref<HTMLButtonElement>;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    mode?: "full" | "compact" | "icon-only";
+    showLabel?: boolean;
+    showChevron?: boolean;
+};
+export declare function PhiAccountMenu({ labels, state, contributedItems, onOpenOverlay, avatarSrc, avatarAlt, icon, triggerRef, open, onOpenChange, mode, showLabel, showChevron, }: PhiAccountMenuProps): import("react").JSX.Element;

package/components/menus/phi-account-menu.js

@@ -0,0 +1,101 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import Link from "next/link";
+import { PhiAvatar } from "../shell/phi-avatar";
+export function PhiAccountMenu({ labels, state, contributedItems, onOpenOverlay, avatarSrc, avatarAlt, icon, triggerRef, open, onOpenChange, mode = "full", showLabel, showChevron, }) {
+    const resolvedShowLabel = showLabel ?? mode === "full";
+    const resolvedShowChevron = showChevron ?? mode !== "icon-only";
+    const guestLoginItems = state.kind === "guest"
+        ? state.loginHref
+            ? [{
+                    key: "login",
+                    label: _jsx(Link, { href: state.loginHref, children: labels.guest.login }),
+                }]
+            : state.onLogin
+                ? [{
+                        key: "login",
+                        label: labels.guest.login,
+                        onClick: state.onLogin,
+                    }]
+                : []
+        : [];
+    /*
+     * A contributed entry is a link when it names a path and a button when it names an Overlay. The menu
+     * control takes both shapes already -- `label` may be an anchor, or plain text with an `onClick` --
+     * so nothing new is needed to render an opener, only to tell the two apart.
+     */
+    const contributedMenuItems = (contributedItems ?? []).map((item) => {
+        if (item.overlayInstanceId) {
+            const overlayInstanceId = item.overlayInstanceId;
+            return {
+                key: item.key,
+                label: item.label,
+                onClick: onOpenOverlay ? () => onOpenOverlay(overlayInstanceId) : undefined,
+                disabled: !onOpenOverlay,
+            };
+        }
+        return {
+            key: item.key,
+            label: item.href ? _jsx(Link, { href: item.href, children: item.label }) : item.label,
+            disabled: !item.href,
+        };
+    });
+    const menuItems = state.kind === "guest"
+        ? [
+            ...guestLoginItems,
+            ...(state.registerHref
+                ? [{
+                        key: "register",
+                        label: _jsx(Link, { href: state.registerHref, children: labels.guest.register }),
+                    }]
+                : []),
+        ]
+        : [
+            ...contributedMenuItems,
+            ...(contributedMenuItems.length > 0
+                ? [{ key: "contributed-divider", type: "divider" }]
+                : []),
+            ...(state.profileHref || state.onProfile
+                ? [
+                    {
+                        key: "profile",
+                        label: state.profileHref
+                            ? _jsx(Link, { href: state.profileHref, children: labels.authenticated.profile })
+                            : labels.authenticated.profile,
+                        onClick: state.profileHref ? undefined : state.onProfile,
+                    },
+                ]
+                : []),
+            ...(state.settingsHref
+                ? [
+                    {
+                        key: "settings",
+                        label: _jsx(Link, { href: state.settingsHref, children: labels.authenticated.settings }),
+                    },
+                ]
+                : []),
+            ...((state.profileHref || state.onProfile || state.settingsHref)
+                ? [
+                    {
+                        key: "account-divider",
+                        type: "divider",
+                    },
+                ]
+                : []),
+            state.logoutHref
+                ? {
+                    key: "logout",
+                    label: _jsx(Link, { href: state.logoutHref, children: labels.authenticated.logout }),
+                }
+                : {
+                    key: "logout",
+                    label: labels.authenticated.logout,
+                    onClick: state.onLogout,
+                },
+        ];
+    return (_jsx(PhiAvatar, { src: avatarSrc, alt: avatarAlt, 
+        // A signed-in person has a name; a guest has none, and falls through to the generic icon.
+        initialsFrom: state.kind === "authenticated" ? state.displayName ?? null : null, icon: icon, label: state.kind === "authenticated"
+            ? (state.displayName ?? labels.trigger.account)
+            : labels.trigger.account, menuItems: menuItems, triggerRef: triggerRef, open: open, onOpenChange: onOpenChange, showLabel: resolvedShowLabel, showChevron: resolvedShowChevron, labelPill: resolvedShowLabel }));
+}

package/components/motion/phi-sequence-viewport.d.ts

@@ -0,0 +1,44 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type PhiMotionEasing, type PhiSequenceAnchor, type PhiSequenceTransition } from "../../helpers/motion";
+import { type PhiCmsMountPolicy } from "../../types/cms-mount-policy";
+export type PhiSequenceViewportProps = {
+    items: readonly ReactNode[];
+    /**
+     * Which item the window is anchored on -- not necessarily the one somebody is looking at. Once more
+     * than one item is visible, "active" splits into what is shown and what the window stands on, and
+     * `anchor` says which end of the window the index means.
+     */
+    activeIndex: number;
+    visibleCount?: number;
+    anchor?: PhiSequenceAnchor;
+    transition?: PhiSequenceTransition;
+    /** Absent means the caller has no opinion and the theme's own pace is used. */
+    durationMs?: number;
+    easing?: PhiMotionEasing;
+    /**
+     * How many items beyond the window stay mounted.
+     *
+     * One number, two jobs, and they are the same job: here it decides which subtrees exist, and in a
+     * gallery the very same window decides which pictures are told to load early. An item that is not
+     * mounted has no images to preload, so the two cannot be set independently without one of them
+     * being wrong.
+     */
+    lookahead?: number;
+    mountPolicy?: PhiCmsMountPolicy;
+    gap?: number | string;
+    style?: CSSProperties;
+    itemStyle?: CSSProperties;
+    className?: string;
+    /** Called for each item with whether it is currently inside the visible window. */
+    renderItem?: (item: ReactNode, state: {
+        index: number;
+        visible: boolean;
+    }) => ReactNode;
+};
+export declare function resolvePhiSequenceWindowStart({ activeIndex, visibleCount, itemCount, anchor, }: {
+    activeIndex: number;
+    visibleCount: number;
+    itemCount: number;
+    anchor: PhiSequenceAnchor;
+}): number;
+export declare function PhiSequenceViewport({ items, activeIndex, visibleCount, anchor, transition, durationMs, easing, lookahead, mountPolicy, gap, style, itemStyle, className, renderItem, }: PhiSequenceViewportProps): import("react").JSX.Element;