@phis/ui 0.1.0 → 0.2.0

package/components/cms/phi-cms-root-page.js

@@ -2,22 +2,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forbidden, notFound, redirect, unauthorized } from "next/navigation";
 import { hasPhiCmsRevisionPreview, loadPhiCmsRootRequest, } from "../../server-helpers/cms-root";
 import { PhiCmsPageRenderer } from "./phi-cms-page-renderer";
-import { localizeAreaPath } from "../../helpers/locale";
-import { resolvePhiPublicLoginHref, resolvePhiUnauthenticatedLoginHref, } from "../../server-helpers/public-login-route";
+import { PhiHardForward } from "./phi-hard-forward";
+import { guardPhiCmsAreaAccess } from "./phi-cms-area-access-guard";
+import { resolvePhiUnauthenticatedLoginHref, } from "../../server-helpers/public-login-route";
 import { resolvePhiCmsPageRedirect, performPhiCmsPageRedirect } from "./phi-cms-page-redirect";
 import { PhiCmsPageMetaSignalEmitter } from "./phi-cms-page-meta-signal-emitter";
 import { isPhiCmsGatewayAuthError } from "../../gateway/errors";
 import { PhiRuntimeControllerServerHost } from "../runtime/runtime-controller-server-host";
 import { materializePhiRuntimeControllerSettings } from "../runtime/runtime-controller-materialization";
 import { PhiCmsRegionType } from "../../constants/phi-cms";
-import { resolvePhiRuntimeModuleIdsForArea, } from "../../plugins/runtime-modules/settings";
-import { resolvePhiCmsRuntimeModuleScope, resolvePhiCmsTreeRuntimeRegistry, } from "./phi-cms-runtime-registry";
+import { resolvePhiCmsAreaRuntimeModuleScope, resolvePhiCmsTreeRuntimeRegistry, } from "./phi-cms-runtime-registry";
 import { PhiRuntimeModuleDataProviderHost } from "../runtime/runtime-module-data-provider-host";
 import { resolvePhiRuntimeControllerDefinitions } from "../../plugins/runtime-modules/resolver";
-import { canPhiViewerAccess } from "../../types/access";
-import { resolvePhiCmsDescriptorCatalog } from "../../plugins/runtime-modules/descriptor-compiler";
 import { buildPhiRuntimeModuleAccessRegistry, filterPhiCmsRenderableTreeForViewer, } from "../../helpers/cms-access-policy";
-import { readPhiAreaPresetRuntimeModuleIds } from "../../helpers/cms-area-config";
 export async function PhiCmsRootPage({ root, path, cmsBridge, }) {
     let rootRequest;
     try {
@@ -55,32 +52,35 @@ export async function PhiCmsRootPage({ root, path, cmsBridge, }) {
     // forward repeats at request speed.
     const pageRedirect = resolvePhiCmsPageRedirect(resolvedRequest.page.page, resolvedRoute.locale, request.pathname);
     if (pageRedirect) {
-        performPhiCmsPageRedirect(pageRedirect);
-    }
-    const areaDefinition = resolvePhiCmsDescriptorCatalog(cmsBridge.runtimeModuleCatalog)
-        .areaDefinitions.get(resolvedRoute.area);
-    if (!isRevisionPreview &&
-        resolvedRoute.rootKind === "area" &&
-        areaDefinition &&
-        !canPhiViewerAccess(resolvedRequest.runtime.viewer, areaDefinition.accessPolicy) &&
-        resolvedRequest.runtime.viewer.resolvedArea) {
-        if (resolvedRequest.runtime.viewer.access === "public" && resolvedRoute.area !== "public") {
-            // Mirrors the Layout guard: fail closed rather than redirect to a route the Auth Module may not
-            // contribute. See AUTHENTICATION.md section 6.
-            const login = await resolvePhiPublicLoginHref(cmsBridge, resolvedRoute.locale, resolvedRequest.runtime.viewer, resolvedRequest.serverCapabilities);
-            if (!login) {
-                unauthorized();
-            }
-            const next = request.pathname?.trim() || `/${resolvedRoute.area}`;
-            redirect(`${login}?${new URLSearchParams({ next }).toString()}`);
+        /*
+         * The same split the Layout makes, for the case the Layout does not see.
+         *
+         * A change of Area re-runs the Layout, and that is where a crossing is answered -- measured. What
+         * reaches here is the navigation the Layout's own comment names: one inside an Area, where the Layout
+         * is not re-rendered and this Page is. A `redirect()` serialised into a client navigation is what the
+         * router struggles with, so a navigation is handed to the browser and a document request keeps its
+         * 307 (components/cms/phi-hard-forward.tsx).
+         *
+         * Only ever cold either way: a warm door is answered by the proxy as a real 307 before anything here
+         * renders.
+         */
+        if (request.clientNavigation) {
+            return _jsx(PhiHardForward, { href: pageRedirect.href });
         }
-        redirect(localizeAreaPath(resolvedRoute.locale, resolvedRequest.runtime.viewer.resolvedArea, "/"));
+        performPhiCmsPageRedirect(pageRedirect);
     }
-    const runtimeModuleIds = resolvePhiRuntimeModuleIdsForArea(resolvedRequest.runtime.area, readPhiAreaPresetRuntimeModuleIds(resolvedRequest.areaPreset, resolvedRequest.runtime.area), [...cmsBridge.runtimeModuleCatalog.values()].map((entry) => entry.definition)).filter((moduleId) => canPhiViewerAccess(resolvedRequest.runtime.viewer, cmsBridge.runtimeModuleCatalog.get(moduleId)?.definition.accessPolicy));
-    const runtimeModuleScope = await resolvePhiCmsRuntimeModuleScope({
+    await guardPhiCmsAreaAccess({
+        cmsBridge,
+        resolvedRoute,
+        viewer: resolvedRequest.runtime.viewer,
+        pathname: request.pathname,
+        serverCapabilities: resolvedRequest.serverCapabilities,
+        isRevisionPreview,
+    });
+    const runtimeModuleScope = await resolvePhiCmsAreaRuntimeModuleScope({
         cmsBridge,
-        moduleIds: runtimeModuleIds,
         area: resolvedRequest.runtime.area,
+        areaPreset: resolvedRequest.areaPreset,
         serverCapabilities: resolvedRequest.serverCapabilities,
     });
     const filteredPageTree = filterPhiCmsRenderableTreeForViewer({
@@ -96,7 +96,7 @@ export async function PhiCmsRootPage({ root, path, cmsBridge, }) {
         tree: filteredPageTree,
         ownerMountScope: "page",
         widgetPluginsByType: runtimeModuleScope.widgetDefinitionsByType,
-        baseSettings: null,
+        baseSettings: resolvedRequest.page.controllerSettings ?? null,
         activeControllerTypes: [...runtimeModuleScope.moduleSet.controllerDescriptorsByType.keys()],
         regionTypes: [PhiCmsRegionType.Content],
         includeOverlays: true,

package/components/cms/phi-cms-root-slot-page.js

@@ -1,7 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { PhiCmsRegionType } from "../../constants/phi-cms";
-import { forbidden, redirect, unauthorized } from "next/navigation";
-import { resolvePhiUnauthenticatedLoginHref } from "../../server-helpers/public-login-route";
 import { PhiCmsLayoutRenderer } from "./phi-cms-layout-renderer";
 import { hasRenderableRegionRoot } from "./phi-cms-region-helpers";
 import { loadPhiCmsRootRequest } from "../../server-helpers/cms-root";
@@ -9,13 +7,10 @@ import { resolvePhiCmsPageRedirect } from "./phi-cms-page-redirect";
 import { isPhiCmsGatewayAuthError } from "../../gateway/errors";
 import { PhiRuntimeControllerServerHost } from "../runtime/runtime-controller-server-host";
 import { materializePhiRuntimeControllerSettings } from "../runtime/runtime-controller-materialization";
-import { resolvePhiRuntimeModuleIdsForArea, } from "../../plugins/runtime-modules/settings";
-import { resolvePhiCmsRuntimeModuleScope, resolvePhiCmsTreeRuntimeRegistry, } from "./phi-cms-runtime-registry";
+import { resolvePhiCmsAreaRuntimeModuleScope, resolvePhiCmsTreeRuntimeRegistry, } from "./phi-cms-runtime-registry";
 import { PhiRuntimeModuleDataProviderHost } from "../runtime/runtime-module-data-provider-host";
 import { resolvePhiRuntimeControllerDefinitions } from "../../plugins/runtime-modules/resolver";
-import { canPhiViewerAccess } from "../../types/access";
 import { buildPhiRuntimeModuleAccessRegistry, filterPhiCmsRenderableTreeForViewer, } from "../../helpers/cms-access-policy";
-import { readPhiAreaPresetRuntimeModuleIds } from "../../helpers/cms-area-config";
 function findRenderableRegion(tree, regionType) {
     return tree.regions.find((region) => region.regionType === regionType);
 }
@@ -46,16 +41,19 @@ export async function PhiCmsRootSlotPage({ root, path, cmsBridge, regionType, })
         });
     }
     catch (error) {
+        /*
+         * A slot refuses nothing, for the same reason it forwards nothing (below).
+         *
+         * The Layout beside it resolves the same request and answers `401` or `403` there, once, with a
+         * status line. Raising it here as well would raise it seven times over -- and a refusal raised from
+         * a parallel slot is worse than a repeat: `redirect`, `unauthorized` and `forbidden` all reach the
+         * client as a navigation, and a navigation asked for by a slot is asked for again the moment the
+         * arriving tree renders that slot again.
+         *
+         * So an Area the viewer may not see draws no Region here and is refused above.
+         */
         if (isPhiCmsGatewayAuthError(error)) {
-            if (error.status === 401) {
-                // Mirrors the Layout: offer the sign-in route when one exists, refuse outright when none does.
-                const login = await resolvePhiUnauthenticatedLoginHref(cmsBridge, root);
-                if (login) {
-                    redirect(login);
-                }
-                unauthorized();
-            }
-            forbidden();
+            return null;
         }
         throw error;
     }
@@ -78,11 +76,10 @@ export async function PhiCmsRootSlotPage({ root, path, cmsBridge, regionType, })
     if (!region || !hasRenderableRegionRoot(resolvedRequest.page, region.rootLayoutNodeId)) {
         return null;
     }
-    const runtimeModuleIds = resolvePhiRuntimeModuleIdsForArea(resolvedRequest.runtime.area, readPhiAreaPresetRuntimeModuleIds(resolvedRequest.areaPreset, resolvedRequest.runtime.area), [...cmsBridge.runtimeModuleCatalog.values()].map((entry) => entry.definition)).filter((moduleId) => canPhiViewerAccess(resolvedRequest.runtime.viewer, cmsBridge.runtimeModuleCatalog.get(moduleId)?.definition.accessPolicy));
-    const runtimeModuleScope = await resolvePhiCmsRuntimeModuleScope({
+    const runtimeModuleScope = await resolvePhiCmsAreaRuntimeModuleScope({
         cmsBridge,
-        moduleIds: runtimeModuleIds,
         area: resolvedRequest.runtime.area,
+        areaPreset: resolvedRequest.areaPreset,
         serverCapabilities: resolvedRequest.serverCapabilities,
     });
     const filteredPageTree = filterPhiCmsRenderableTreeForViewer({
@@ -103,7 +100,7 @@ export async function PhiCmsRootSlotPage({ root, path, cmsBridge, regionType, })
         tree: filteredPageTree,
         ownerMountScope: "page",
         widgetPluginsByType: runtimeModuleScope.widgetDefinitionsByType,
-        baseSettings: null,
+        baseSettings: resolvedRequest.page.controllerSettings ?? null,
         activeControllerTypes: [...runtimeModuleScope.moduleSet.controllerDescriptorsByType.keys()],
         regionTypes: [regionType],
     });

package/components/cms/phi-cms-runtime-registry.d.ts

@@ -3,6 +3,7 @@ import type { PhiResolvedCmsRenderableTree } from "../../types/cms";
 import type { PhiCmsSiteBridge, PhiRuntimeModuleCatalog, PhiRuntimeModuleId } from "../../types/cms-plugins";
 import type { PhiCmsAreaKey } from "../../constants/cms-areas";
 import type { PhiCapabilitySnapshot } from "../../types/server-capabilities";
+import { readPhiAreaPresetRuntimeModuleIds } from "../../helpers/cms-area-config";
 export declare function resolvePhiCmsRuntimeModuleScope({ cmsBridge, moduleIds, area, serverCapabilities, }: {
     cmsBridge: PhiCmsSiteBridge;
     moduleIds?: readonly PhiRuntimeModuleId[] | null;
@@ -10,11 +11,28 @@ export declare function resolvePhiCmsRuntimeModuleScope({ cmsBridge, moduleIds,
     serverCapabilities: PhiCapabilitySnapshot | null;
 }): Promise<{
     catalog: PhiRuntimeModuleCatalog;
-    moduleSet: import("../../types").PhiResolvedRuntimeModuleSet;
+    moduleSet: import("../../types/cms-plugins").PhiResolvedRuntimeModuleSet;
+    serverCapabilities: PhiCapabilitySnapshot | null;
+    widgetDefinitionsByType: Map<string, import("../../types").PhiCmsWidgetPluginDefinition<unknown>>;
+}>;
+/**
+ * The Module scope of an Area, from the selection its preset states.
+ *
+ * Which Modules this Area runs, and not which ones this person may see. A Module is area-bound and
+ * never switched off for a reader (ACCESS.md); what its Widgets show may still differ per person.
+ */
+export declare function resolvePhiCmsAreaRuntimeModuleScope({ cmsBridge, area, areaPreset, serverCapabilities, }: {
+    cmsBridge: PhiCmsSiteBridge;
+    area: PhiCmsAreaKey;
+    areaPreset: Parameters<typeof readPhiAreaPresetRuntimeModuleIds>[0];
+    serverCapabilities: PhiCapabilitySnapshot | null;
+}): Promise<{
+    catalog: PhiRuntimeModuleCatalog;
+    moduleSet: import("../../types/cms-plugins").PhiResolvedRuntimeModuleSet;
     serverCapabilities: PhiCapabilitySnapshot | null;
     widgetDefinitionsByType: Map<string, import("../../types").PhiCmsWidgetPluginDefinition<unknown>>;
 }>;
 export declare function resolvePhiCmsTreeRuntimeRegistry({ moduleScope, trees, }: {
     moduleScope: Awaited<ReturnType<typeof resolvePhiCmsRuntimeModuleScope>>;
     trees: readonly PhiResolvedCmsRenderableTree[];
-}): Promise<import("../../types").PhiCmsRuntimeRenderRegistry>;
+}): Promise<import("../../types/cms-plugins").PhiCmsRuntimeRenderRegistry>;

package/components/cms/phi-cms-runtime-registry.js

@@ -1,6 +1,8 @@
 import "server-only";
 import { cache } from "react";
 import { resolvePhiRuntimeModuleSet, resolvePhiRuntimeRenderRegistry, } from "../../plugins/runtime-modules/resolver";
+import { resolvePhiRuntimeModuleIdsForArea } from "../../plugins/runtime-modules/settings";
+import { readPhiAreaPresetRuntimeModuleIds } from "../../helpers/cms-area-config";
 const resolvePhiCmsRuntimeModuleScopeForRequest = cache(async (catalog, area, moduleIdsKey, serverCapabilitiesKey) => {
     const moduleIds = JSON.parse(moduleIdsKey);
     const serverCapabilities = JSON.parse(serverCapabilitiesKey);
@@ -21,6 +23,16 @@ const resolvePhiCmsRuntimeModuleScopeForRequest = cache(async (catalog, area, mo
 export function resolvePhiCmsRuntimeModuleScope({ cmsBridge, moduleIds, area, serverCapabilities, }) {
     return resolvePhiCmsRuntimeModuleScopeForRequest(cmsBridge.runtimeModuleCatalog, area, JSON.stringify(moduleIds ?? []), JSON.stringify(serverCapabilities));
 }
+/**
+ * The Module scope of an Area, from the selection its preset states.
+ *
+ * Which Modules this Area runs, and not which ones this person may see. A Module is area-bound and
+ * never switched off for a reader (ACCESS.md); what its Widgets show may still differ per person.
+ */
+export function resolvePhiCmsAreaRuntimeModuleScope({ cmsBridge, area, areaPreset, serverCapabilities, }) {
+    const moduleIds = resolvePhiRuntimeModuleIdsForArea(area, readPhiAreaPresetRuntimeModuleIds(areaPreset, area), [...cmsBridge.runtimeModuleCatalog.values()].map((entry) => entry.definition));
+    return resolvePhiCmsRuntimeModuleScope({ cmsBridge, moduleIds, area, serverCapabilities });
+}
 export function resolvePhiCmsTreeRuntimeRegistry({ moduleScope, trees, }) {
     return resolvePhiRuntimeRenderRegistry({
         catalog: moduleScope.catalog,

package/components/cms/phi-hard-forward.d.ts

@@ -0,0 +1,21 @@
+/**
+ * An Area root forwarding a client navigation, as a document request rather than a router redirect.
+ *
+ * `redirect()` reaches a client navigation as a serialised `NEXT_REDIRECT`, and applying one that also
+ * changes the Area leaves Next's router asking for the same address at request speed -- 42 to 110
+ * navigations, measured, never settling
+ * (`browser-test/notes/ANALYSE-area-switch-loop.md`). `location.replace` hands the forward to the browser
+ * instead, which builds the arriving Area from nothing: three navigations, two documents, quiet.
+ *
+ * **Only where the proxy could not answer.** A warm door is forwarded by the proxy as a real HTTP 307
+ * before a router state tree exists at all, which costs one navigation and no flash
+ * (`gateway/area-root-door.ts`). This is the cold path, and it is the reason the cold path is no longer a
+ * loop -- at the price of one empty render the visitor sees for a moment.
+ *
+ * **And only for a client navigation.** A document request keeps its 307: the status line is how a
+ * forwarding Area root stays out of an index as a page, which `PhiCmsAreaBoundary` says at the call site.
+ * `replace` rather than `assign`, so the address that forwarded does not become a back-button stop.
+ */
+export declare function PhiHardForward({ href }: {
+    href: string;
+}): null;

package/components/cms/phi-hard-forward.js

@@ -0,0 +1,26 @@
+"use client";
+import { useEffect } from "react";
+/**
+ * An Area root forwarding a client navigation, as a document request rather than a router redirect.
+ *
+ * `redirect()` reaches a client navigation as a serialised `NEXT_REDIRECT`, and applying one that also
+ * changes the Area leaves Next's router asking for the same address at request speed -- 42 to 110
+ * navigations, measured, never settling
+ * (`browser-test/notes/ANALYSE-area-switch-loop.md`). `location.replace` hands the forward to the browser
+ * instead, which builds the arriving Area from nothing: three navigations, two documents, quiet.
+ *
+ * **Only where the proxy could not answer.** A warm door is forwarded by the proxy as a real HTTP 307
+ * before a router state tree exists at all, which costs one navigation and no flash
+ * (`gateway/area-root-door.ts`). This is the cold path, and it is the reason the cold path is no longer a
+ * loop -- at the price of one empty render the visitor sees for a moment.
+ *
+ * **And only for a client navigation.** A document request keeps its 307: the status line is how a
+ * forwarding Area root stays out of an index as a page, which `PhiCmsAreaBoundary` says at the call site.
+ * `replace` rather than `assign`, so the address that forwarded does not become a back-button stop.
+ */
+export function PhiHardForward({ href }) {
+    useEffect(() => {
+        window.location.replace(href);
+    }, [href]);
+    return null;
+}

package/components/controls/phi-accordion-control.d.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+/**
+ * A stack of sections where one is open at a time.
+ *
+ * What the Theme inspector repeated four times, byte for byte apart from the state it was bound to --
+ * and the whole of what it repeated was an undoing. Three `styles` overrides took the panel look back
+ * off the primitive: a transparent ground instead of a filled one, and no inline padding on the header
+ * or the body. An inspector section is not a panel; it is a heading with things under it, and the box
+ * around it belongs to whatever the inspector is already standing in.
+ *
+ * **One open at a time is the shape, not a prop.** Sections fold so a long inspector stays short, which
+ * only works if opening one closes the last. A region of a page that folds independently is the
+ * CollapsibleLayout, which owns the primitive's full surface -- this is the narrow case, and it has
+ * nothing to decide.
+ *
+ * It is controlled, because every caller already keeps the open section somewhere it survives a reload,
+ * and a Control that also kept its own would give them two answers to the same question.
+ */
+export type PhiAccordionControlSection = {
+    key: string;
+    label: ReactNode;
+    children: ReactNode;
+};
+export type PhiAccordionControlProps = {
+    sections: readonly PhiAccordionControlSection[];
+    /** The open section. An empty string, or a key no section carries, opens none. */
+    openSection?: string;
+    onOpenSectionChange?: (key: string) => void;
+};
+export declare function PhiAccordionControl({ sections, openSection, onOpenSectionChange, }: PhiAccordionControlProps): import("react").JSX.Element;

package/components/controls/phi-accordion-control.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Collapse } from "antd";
+export function PhiAccordionControl({ sections, openSection = "", onOpenSectionChange, }) {
+    return (_jsx(Collapse, { accordion: true, bordered: false, size: "small", activeKey: openSection, 
+        // An accordion closes the last section as it opens the next, so the primitive still answers with a
+        // list and it is always the one key or none.
+        onChange: (keys) => onOpenSectionChange?.(Array.isArray(keys) ? keys[0] ?? "" : String(keys ?? "")), styles: {
+            root: { background: "transparent" },
+            header: { alignItems: "center", paddingInline: 0 },
+            body: { paddingInline: 0 },
+        }, items: sections.map((section) => ({
+            key: section.key,
+            label: section.label,
+            children: section.children,
+        })) }));
+}

package/components/controls/phi-alert-control.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import type { PhiFeedbackLevel } from "../../types/control";
 export type PhiAlertControlProps = {
     level: PhiFeedbackLevel;

package/components/controls/phi-alert-control.js

@@ -1,6 +1,16 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Alert } from "antd";
+import { lazy, Suspense } from "react";
+/*
+ * Ant Design's Alert, loaded where an alert is actually shown. The render diagnostic reaches every page
+ * through the CMS renderer and the forms and auth widgets hold one for their error state, but an alert is
+ * drawn only when something went wrong -- so a static import paid for it on every page that never shows one.
+ */
+const PhiLazyAlert = lazy(() => import("antd/es/alert"));
 export function PhiAlertControl({ level, title, description, variant = "outlined", showIcon, dismissible, onDismiss, }) {
-    return (_jsx(Alert, { type: level, title: title, description: description, variant: variant, showIcon: showIcon, closable: dismissible ? { onClose: onDismiss } : false }));
+    /*
+     * Rendered on the Server it is complete. Raised in the browser, the alert appears once its chunk is
+     * there.
+     */
+    return (_jsx(Suspense, { fallback: null, children: _jsx(PhiLazyAlert, { type: level, title: title, description: description, variant: variant, showIcon: showIcon, closable: dismissible ? { onClose: onDismiss } : false }) }));
 }

package/components/controls/phi-avatar-control.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+/**
+ * Who this is, in the space of a picture.
+ *
+ * **Three steps, in this order: the picture, then initials, then the generic silhouette.** Initials
+ * matter because "no picture" is the ordinary state -- most people never choose one -- and a row of
+ * identical grey silhouettes tells a reader nothing, while two letters tell them who. The rule was
+ * written down once, in the account menu, and the account page's own avatar was drawing the silhouette
+ * straight away; a person with a name and no picture therefore looked different depending on which
+ * surface was showing them. That is a platform decision about how people are identified, not a
+ * per-surface one, so it lives here.
+ *
+ * The fallback order is the primitive's own: Ant Design draws `children` only when `src` is absent or
+ * fails, which means a broken picture lands on the initials rather than on nothing.
+ *
+ * A caller with no name to offer gets the silhouette, and that is the honest outcome rather than a
+ * choice -- `initialsFrom` is what a surface passes when it knows who it is drawing.
+ */
+export type PhiAvatarControlProps = {
+    src?: string;
+    alt?: string;
+    /** The name the initials are taken from when there is no picture. */
+    initialsFrom?: string | null;
+    /**
+     * A different silhouette for the last step, where a surface draws something other than a person --
+     * never a way to skip the initials.
+     */
+    icon?: ReactNode;
+    size?: number;
+};
+export declare function PhiAvatarControl({ src, alt, initialsFrom, icon, size }: PhiAvatarControlProps): import("react").JSX.Element;

package/components/controls/phi-avatar-control.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { UserOutlined } from "@ant-design/icons";
+import { Avatar } from "antd";
+/**
+ * Two letters from a name: the first of the first two words, or the first two of a single word.
+ *
+ * Works on what it is given rather than on a first/last name pair, because the callers hold different
+ * shapes -- a display name, a full name, sometimes an address local part -- and none of them should
+ * have to split it themselves.
+ */
+function readPhiAvatarInitials(value) {
+    const words = (value ?? "").trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+        return null;
+    }
+    const letters = words.length === 1
+        ? [...words[0]].slice(0, 2)
+        : [words[0], words[1]].map((word) => [...word][0]);
+    const initials = letters.join("").toLocaleUpperCase();
+    return initials || null;
+}
+export function PhiAvatarControl({ src, alt, initialsFrom, icon, size = 32 }) {
+    const initials = src ? null : readPhiAvatarInitials(initialsFrom);
+    return (_jsx(Avatar, { size: size, src: src, alt: alt, icon: src || initials ? icon : icon ?? _jsx(UserOutlined, {}), style: { flexShrink: 0 }, children: initials }));
+}

package/components/controls/phi-background-control.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from "react";
-import { Button, Divider, Flex, Input, InputNumber, Select, Space, Typography, theme } from "antd";
-import { PHI_BACKGROUND_BASE_KINDS, PHI_BACKGROUND_IMAGE_SOURCE_KINDS, PHI_BACKGROUND_MOTION_MODES, PHI_BACKGROUND_OVERLAY_DEFAULT_OPACITY, PHI_BACKGROUND_PARALLAX_DEFAULT_STRENGTH, phiBackgroundBaseSupportsGlassEffect, resolvePhiBackgroundParallaxDefaultStrength, normalizePhiBackgroundWidgetConfig, readPhiBackgroundPatternInkFromCss, resolvePhiBackgroundWidgetStyle, serializePhiBackgroundBaseCss, serializePhiBackgroundPatternInkCss, } from "../widgets/config/background";
+import { Button, Divider, Flex, Input, InputNumber, Select, Typography, theme } from "antd";
+import { PhiFlexControl } from "./phi-flex-control";
+import { PHI_BACKGROUND_BASE_KINDS, PHI_BACKGROUND_IMAGE_SOURCE_KINDS, PHI_BACKGROUND_MOTION_MODES, PHI_BACKGROUND_OVERLAY_DEFAULT_OPACITY, PHI_BACKGROUND_PARALLAX_DEFAULT_STRENGTH, phiBackgroundBaseSupportsGlassEffect, resolvePhiBackgroundParallaxDefaultStrength, normalizePhiBackgroundWidgetConfig, readPhiBackgroundGradientCss, readPhiBackgroundPatternInkFromCss, resolvePhiBackgroundWidgetStyle, serializePhiBackgroundBaseCss, serializePhiBackgroundPatternInkCss, } from "../widgets/config/background";
 import { PHI_CORE_BACKGROUND_PATTERN_PROVIDERS, resolvePhiBackgroundPatternDefaultValues, resolvePhiBackgroundPatternProvider, } from "../widgets/config/background-pattern-authoring";
 import { PHI_DEFAULT_BACKGROUND_PATTERN_KEY, } from "../widgets/config/background-pattern-contract";
 import { PHI_BACKGROUND_COLOR_OVERLAY_DEFAULT_INK, PHI_BACKGROUND_PATTERN_DEFAULT_INK, resolvePhiBackgroundPatternLiveLayer, } from "../widgets/config/background-pattern-live";
@@ -17,6 +18,7 @@ import { PhiSliderControl } from "./phi-slider-control";
 import { PhiSelectControl } from "./phi-select-control";
 import { PHI_COLOR_PICKER_DEFAULT_LABELS } from "../widgets/label-types/color-picker";
 import { usePhiColorControlPresets } from "./use-phi-color-control-presets";
+import { PhiCompactGroupControl } from "./phi-compact-group-control";
 const BACKGROUND_DIRECTION_OPTIONS = [
     { value: "0deg", label: "↑" },
     { value: "45deg", label: "↗" },
@@ -278,9 +280,13 @@ export function PhiBackgroundControl({ value, config, disabled = false, mode = "
             emit(snapshot);
     }
     function updateBaseFromCss(css) {
-        const nextBase = normalizePhiBackgroundWidgetConfig({
-            background: resolveStoredSolidColor(css),
-        }).base;
+        const storedCss = resolveStoredSolidColor(css);
+        // A gradient the Base cannot hold is refused, and the Base keeps what it had; stored as a colour it
+        // would lose its stops the next time anybody opened it.
+        if (readPhiBackgroundGradientCss(storedCss)?.problem) {
+            return;
+        }
+        const nextBase = normalizePhiBackgroundWidgetConfig({ background: storedCss }).base;
         if (currentValue.base.kind === "gradient" && nextBase.kind === "color") {
             emit({
                 ...currentValue,
@@ -406,7 +412,7 @@ export function PhiBackgroundControl({ value, config, disabled = false, mode = "
         return (_jsx(_Fragment, { children: BACKGROUND_DIRECTION_OPTIONS.map((option) => (_jsx(Button, { "aria-label": option.value, type: directionToDegrees(option.value) === resolvedDegrees ? "primary" : "default", disabled: isDisabled, onClick: () => onDirectionChange(option.value), style: { minWidth: token.controlHeight, paddingInline: 0 }, children: option.label }, option.value))) }));
     }
     function renderDirectionEditor(label, value, onDirectionChange, key) {
-        return (_jsxs(Flex, { vertical: true, gap: token.paddingXS, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: label }), _jsxs(Space.Compact, { block: true, style: { width: "100%" }, children: [renderDirectionButtons(value, onDirectionChange), _jsx(InputNumber, { min: 0, max: 360, step: 1, value: directionToDegrees(value), disabled: isDisabled, suffix: "\u00B0", onChange: (next) => onDirectionChange(degreesToDirection(typeof next === "number" ? next : 90)), styles: { input: { textAlign: "right" } }, style: {
+        return (_jsxs(Flex, { vertical: true, gap: token.paddingXS, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: label }), _jsxs(PhiCompactGroupControl, { block: true, style: { width: "100%" }, children: [renderDirectionButtons(value, onDirectionChange), _jsx(InputNumber, { min: 0, max: 360, step: 1, value: directionToDegrees(value), disabled: isDisabled, suffix: "\u00B0", onChange: (next) => onDirectionChange(degreesToDirection(typeof next === "number" ? next : 90)), styles: { input: { textAlign: "right" } }, style: {
                                 flex: "1 1 0",
                                 minWidth: 0,
                                 width: 0,
@@ -667,7 +673,7 @@ export function PhiBackgroundControl({ value, config, disabled = false, mode = "
         return (_jsx(ConfigPreviewShell, { expanded: canOpenPreview, children: renderPreviewPicker() }));
     }
     const showPreview = mode !== "config";
-    return (_jsxs(Space, { orientation: "vertical", size: 12, style: { width: "100%" }, children: [showPreview ? (_jsx(ConfigPreviewShell, { expanded: canOpenPreview, children: renderPreviewPicker() })) : null, _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingXS, width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.base }), _jsx(PhiSegmentedControl, { block: true, value: currentValue.base.kind, options: baseKindOptions, onChange: (next) => updateBaseKind(next) })] }), currentValue.base.kind === "image" ? (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingSM, width: "100%" }, children: [_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingXS, wrap: false, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.image }), currentValue.base.sourceKind === "asset" && currentValue.base.assetId != null ? (_jsx(Typography.Text, { type: "secondary", style: { fontSize: token.fontSizeSM, textAlign: "right" }, children: currentValue.base.assetId })) : null] }), _jsxs("div", { style: {
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: 12, style: { width: "100%" }, children: [showPreview ? (_jsx(ConfigPreviewShell, { expanded: canOpenPreview, children: renderPreviewPicker() })) : null, _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingXS, width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.base }), _jsx(PhiSegmentedControl, { block: true, value: currentValue.base.kind, options: baseKindOptions, onChange: (next) => updateBaseKind(next) })] }), currentValue.base.kind === "image" ? (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingSM, width: "100%" }, children: [_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingXS, wrap: false, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.image }), currentValue.base.sourceKind === "asset" && currentValue.base.assetId != null ? (_jsx(Typography.Text, { type: "secondary", style: { fontSize: token.fontSizeSM, textAlign: "right" }, children: currentValue.base.assetId })) : null] }), _jsxs("div", { style: {
                             display: "grid",
                             gridTemplateColumns: "repeat(2, minmax(0, 1fr))",
                             gap: token.paddingSM,
@@ -699,7 +705,7 @@ export function PhiBackgroundControl({ value, config, disabled = false, mode = "
                                 } })] })) : (_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingSM, wrap: "wrap", children: [_jsx(Typography.Text, { children: labels.base.gradient }), _jsx(PhiColorControl, { ...colorPickerTransaction, mode: "gradient", value: derivedPickerValue, disabled: isDisabled, presets: colorPickerPresets, placement: colorPickerPlacement, onChange: (value) => {
                                     if (value != null)
                                         updateBaseFromCss(value);
-                                } })] })), currentValue.base.kind === "gradient" ? (renderDirectionEditor(labels.gradient.direction, currentValue.base.direction, updateGradientDirection)) : null] })) : null, _jsx(Divider, { dashed: true, size: "small" }), _jsxs(Space, { orientation: "vertical", size: 8, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.overlay }), _jsx(PhiSegmentedControl, { block: true, value: currentValue.overlay?.kind ?? "none", options: overlayKindOptions, onChange: (next) => updateOverlayKind(next) }), currentValue.overlay ? (_jsxs(Space, { orientation: "vertical", size: 8, style: { width: "100%" }, children: [currentValue.overlay.kind === "pattern" ? (_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingSM, wrap: "wrap", children: [_jsx(Typography.Text, { children: labels.overlay.pattern }), _jsx(PhiSelectControl, { value: currentValue.overlay.patternKey, options: resolvedPatternOptions, disabled: isDisabled, style: { width: fieldControlWidth }, onChange: (patternKey) => {
+                                } })] })), currentValue.base.kind === "gradient" ? (renderDirectionEditor(labels.gradient.direction, currentValue.base.direction, updateGradientDirection)) : null] })) : null, _jsx(Divider, { dashed: true, size: "small" }), _jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.overlay }), _jsx(PhiSegmentedControl, { block: true, value: currentValue.overlay?.kind ?? "none", options: overlayKindOptions, onChange: (next) => updateOverlayKind(next) }), currentValue.overlay ? (_jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%" }, children: [currentValue.overlay.kind === "pattern" ? (_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingSM, wrap: "wrap", children: [_jsx(Typography.Text, { children: labels.overlay.pattern }), _jsx(PhiSelectControl, { value: currentValue.overlay.patternKey, options: resolvedPatternOptions, disabled: isDisabled, style: { width: fieldControlWidth }, onChange: (patternKey) => {
                                             const provider = resolvePhiBackgroundPatternProvider(patternKey);
                                             if (!provider)
                                                 return;
@@ -779,5 +785,5 @@ export function PhiBackgroundControl({ value, config, disabled = false, mode = "
                                                     });
                                                 }, style: { width: fieldControlWidth } })] }, field.key));
                                 })
-                                : null] })) : null] }), effectKindOptions.length > 1 ? (_jsxs(_Fragment, { children: [_jsx(Divider, { dashed: true, size: "small" }), _jsxs(Space, { orientation: "vertical", size: 8, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.effect }), _jsx(PhiSegmentedControl, { block: true, value: activeEffectKind, options: effectKindOptions, onChange: (next) => updateEffectKind(next) })] })] })) : null] }));
+                                : null] })) : null] }), effectKindOptions.length > 1 ? (_jsxs(_Fragment, { children: [_jsx(Divider, { dashed: true, size: "small" }), _jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%" }, children: [_jsx(Typography.Text, { children: labels.sections.effect }), _jsx(PhiSegmentedControl, { block: true, value: activeEffectKind, options: effectKindOptions, onChange: (next) => updateEffectKind(next) })] })] })) : null] }));
 }

package/components/controls/phi-border-control.js

@@ -1,12 +1,13 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { InputNumber, Select, Space, Typography, theme } from "antd";
+import { InputNumber, Select, Typography, theme } from "antd";
 import { resolvePhiBorderWidgetStyle } from "../../helpers/border-widget-style";
 import { mergePhiBorderWidgetConfig, } from "../../types/cms-config";
 import { PHI_BORDER_WIDGET_DEFAULT_LABELS, } from "../widgets/label-types/border";
 import { ConfigPreviewShell } from "./config-preview-shell";
 import { PhiBoundRadiusControl } from "./phi-bound-radius-control";
 import { PhiColorControl } from "./phi-color-control";
+import { PhiCompactGroupControl } from "./phi-compact-group-control";
 const BORDER_STYLE_OPTIONS = [
     { value: "solid", label: "Solid" },
     { value: "dashed", label: "Dashed" },
@@ -57,7 +58,7 @@ export function PhiBorderControl({ value, config, disabled = false, mode = "cont
                         rowGap: token.paddingXS,
                         alignItems: "center",
                         width: "100%",
-                    }, children: [_jsx(Typography.Text, { children: labels.fields.style }), _jsxs(Space.Compact, { style: { width: "100%" }, children: [_jsx(InputNumber, { disabled: isDisabled, value: resolvedValue.borderWidth, min: 0, step: 0.5, precision: 2, placeholder: labels.placeholders.width, onChange: (nextWidth) => {
+                    }, children: [_jsx(Typography.Text, { children: labels.fields.style }), _jsxs(PhiCompactGroupControl, { style: { width: "100%" }, children: [_jsx(InputNumber, { disabled: isDisabled, value: resolvedValue.borderWidth, min: 0, step: 0.5, precision: 2, placeholder: labels.placeholders.width, onChange: (nextWidth) => {
                                         emit({
                                             borderWidth: typeof nextWidth === "number" ? nextWidth : resolvedValue.borderWidth,
                                         });

package/components/controls/phi-brand-control.d.ts

@@ -1,14 +1,19 @@
-import type { ReactNode } from "react";
+import type { CSSProperties, ReactNode } from "react";
 import type { PhiThemeMode } from "../../theme/phi-theme-presets";
-import type { PhiSiteThemeBrand } from "../../types/site-theme";
+import type { PhiSiteThemeBrand, PhiSiteThemeBrandLine } from "../../types/site-theme";
+/**
+ * Which parts of the Brand are drawn here.
+ *
+ * `lockup` is the pairing of the two, which is what the trade calls it. The Eyebrow belongs to the
+ * Wordmark and travels with it: it is the line above the name, and above a bare Logo it would sit over
+ * nothing.
+ */
+export type PhiBrandControlShows = "lockup" | "logo" | "wordmark";
 export type PhiBrandControlProps = {
     brand?: PhiSiteThemeBrand | null;
     /** The Site's own name, for a Brand that has no Wordmark parts of its own. */
     fallbackTitle?: ReactNode;
-    fallbackEyebrow?: ReactNode;
-    showLogo?: boolean;
-    /** Optical correction for a Logo whose artwork does not sit on its own baseline. */
-    logoYOffset?: number;
+    shows?: PhiBrandControlShows;
     /** The mode whose Logo is drawn: a Logo is artwork in fixed colours, one picture per mode. */
     mode: PhiThemeMode;
 };
@@ -19,13 +24,39 @@ export type PhiBrandControlProps = {
  * from the id, which is the same address without its revision.
  */
 export declare function resolvePhiBrandLogoUrl(brand: PhiSiteThemeBrand | null | undefined, mode: PhiThemeMode): string | null;
+export type PhiBrandLineControlProps = {
+    line?: PhiSiteThemeBrandLine | null;
+    /** Drawn when the line names no icon of its own. */
+    fallbackIcon?: string;
+    /**
+     * How the line is set where the placement says so -- a resolved family and size, as the Wordmark above
+     * is given its own.
+     *
+     * What the line *says* is Brand and is read from the Theme; how large it is drawn is not. The same
+     * sentence stands in a header strip and in a footer column, and those are two sizes. Nothing given
+     * inherits, which is what the Theme workspace preview wants: it shows the Brand, not a placement of it.
+     */
+    fontFamily?: CSSProperties["fontFamily"];
+    fontSize?: CSSProperties["fontSize"];
+};
+/**
+ * One of the two lines a Brand carries: what it says, with its icon in front of it.
+ *
+ * A line is Brand, which is why it is drawn here beside the Wordmark rather than by whatever Widget
+ * happens to stand in that slot. A Simple Text used to hold a copy of the sentence, written in when
+ * the Preset was built; what it showed was therefore whatever the Brand said that day.
+ *
+ * Nothing set means nothing drawn. The frame keeps its shape without the line, and an empty line with
+ * an icon in front of it would say that something is missing rather than that nothing was asked for.
+ */
+export declare function PhiBrandLineControl({ line, fallbackIcon, fontFamily, fontSize, }: PhiBrandLineControlProps): import("react").JSX.Element | null;
 /**
  * Whether a Brand has anything at all to show.
  *
  * The Widget asks before it wraps: a Brand with no Logo, no Wordmark and no Eyebrow must not become an
  * empty link that still fills its Region and still takes the click.
  */
-export declare function phiBrandControlIsEmpty({ brand, fallbackTitle, fallbackEyebrow, showLogo, mode, }: PhiBrandControlProps): boolean;
+export declare function phiBrandControlIsEmpty({ brand, fallbackTitle, shows, mode, }: PhiBrandControlProps): boolean;
 /**
  * The Brand as it looks: Logo, Eyebrow and Wordmark, and nothing about where it leads.
  *
@@ -34,4 +65,4 @@ export declare function phiBrandControlIsEmpty({ brand, fallbackTitle, fallbackE
  * like while it is being set. The preview used to import the Widget for it, which is the one thing a
  * Widget may not do to another Widget; what it actually needed was this.
  */
-export declare function PhiBrandControl({ brand, fallbackTitle, fallbackEyebrow, showLogo, logoYOffset, mode, }: PhiBrandControlProps): import("react").JSX.Element | null;
+export declare function PhiBrandControl({ brand, fallbackTitle, shows, mode, }: PhiBrandControlProps): import("react").JSX.Element | null;