@phis/ui 0.4.3 → 0.4.4

package/plugins/runtime-modules/builder/render-root-node-scaffold.js

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { cloneElement, isValidElement, Suspense, useCallback, useEffect, useRef, useState } from "react";
-import { usePhiConfig } from "../../../components/root/phi-config-provider";
+import { usePhiPageModeToken } from "../../../components/root/phi-config-provider";
+import { usePhiPageModeTone } from "../../../components/surface/phi-surface-tone";
 import { PhiEditScaffoldDrawer } from "./edit-scaffold-drawer";
 import { comparePhiCmsInstanceIds } from "../../../types/cms-instance-id";
 import { PhiSlotChildFrame } from "../../../plugins/runtime/phi-slot-child-frame";
@@ -10,7 +11,7 @@ import { PhiPlusButtonWidget, } from "./clients/layout-scaffold-buttons";
 import { usePhiStructureDroppable, } from "./structure-dnd";
 import { PhiInlineTextEditor } from "../../../components/controls/phi-inline-text-editor";
 import { PhiButtonControl } from "../../../components/controls/phi-button-control";
-import { usePhiAuthoringLayoutDefinition, usePhiRuntimeModuleAuthoringRegistration, } from "../../../plugins/runtime-modules/client-authoring-module";
+import { usePhiAuthoringLayoutDefinitionResolver, usePhiRuntimeModuleAuthoringRegistration, } from "../../../plugins/runtime-modules/client-authoring-module";
 import { usePhiRuntimeModuleState } from "../../../components/runtime/runtime-module-context";
 import { PhiCmsRenderDiagnostic } from "../../../components/cms/phi-cms-render-diagnostic";
 import { PhiCmsRenderErrorBoundary } from "../../../components/cms/phi-cms-render-error-boundary";
@@ -116,7 +117,8 @@ function PhiAuthoringWidgetLoader({ widget, config, slotSizePolicy, demandContro
 function PhiAuthoringLayoutLoader({ type, kind, blockId, children, }) {
     const activeModules = usePhiRuntimeModuleState();
     const layoutType = resolvePhiAuthoringLayoutType(type);
-    const definition = usePhiAuthoringLayoutDefinition(layoutType);
+    const resolveLayoutDefinition = usePhiAuthoringLayoutDefinitionResolver();
+    const definition = resolveLayoutDefinition(layoutType);
     if (!definition) {
         return _jsx(PhiCmsRenderDiagnostic, { issue: {
                 code: "missing-renderer",
@@ -138,7 +140,7 @@ function PhiAuthoringLayoutLoader({ type, kind, blockId, children, }) {
             } });
     }
     const LazyAuthoringLayout = definition.component;
-    return (_jsx(PhiCmsRenderErrorBoundary, { kind: kind, blockId: blockId, typeKey: type, moduleId: definition.ownerModuleId, children: _jsx(Suspense, { fallback: null, children: _jsx(LazyAuthoringLayout, { children: (plugin) => children(plugin, definition, activeModules.widgetDefinitionsByType) }) }) }));
+    return (_jsx(PhiCmsRenderErrorBoundary, { kind: kind, blockId: blockId, typeKey: type, moduleId: definition.ownerModuleId, children: _jsx(Suspense, { fallback: null, children: _jsx(LazyAuthoringLayout, { children: (plugin) => children(plugin, definition, activeModules.widgetDefinitionsByType, resolveLayoutDefinition) }) }) }));
 }
 function resolveRootNodeEditSlotAnchor(rootNode) {
     return rootNode.editSlotAnchor ?? undefined;
@@ -206,10 +208,12 @@ function resolveEffectsPreviewDurationMs(config) {
 }
 function PhiEffectsPreviewButton({ config, blockKind, onRun, }) {
     const previewLabel = formatEffectsPreviewLabel(config, blockKind);
+    // In the editor's mode, not a tone's: the button is the Builder's, whatever mode the Widget is drawn in.
+    const pageModeTone = usePhiPageModeTone();
     return (_jsx("span", { style: { display: "contents" }, onMouseDown: (event) => {
             event.preventDefault();
             event.stopPropagation();
-        }, onClick: (event) => event.stopPropagation(), children: _jsx(PhiButtonControl, { className: "phi-layout-affordance phi-layout-affordance--effects-preview", ariaLabel: previewLabel, tooltip: previewLabel, icon: _jsx(PhiIcon, { name: "node-index", size: "inherit" }), type: "text", size: "small", onClick: onRun, style: {
+        }, onClick: (event) => event.stopPropagation(), children: pageModeTone.wrap(_jsx(PhiButtonControl, { className: "phi-layout-affordance phi-layout-affordance--effects-preview", ariaLabel: previewLabel, tooltip: previewLabel, icon: _jsx(PhiIcon, { name: "node-index", size: "inherit" }), type: "text", size: "small", onClick: onRun, style: {
                 position: "absolute",
                 top: "50%",
                 left: "50%",
@@ -219,7 +223,7 @@ function PhiEffectsPreviewButton({ config, blockKind, onRun, }) {
                 // whose children `styles/layout.css` stretches, and a stylesheet answer did not hold there.
                 width: "var(--ant-control-height)",
                 "--phi-layout-affordance-size": "var(--ant-control-height)",
-            } }) }));
+            } })) }));
 }
 function PhiSignalWiringToolButton({ onOpen }) {
     return (_jsx("span", { style: { display: "contents" }, onPointerDown: (event) => {
@@ -264,7 +268,8 @@ function findPhiWidgetAuthoringTextTarget(container, clientX, clientY) {
     }) ?? null;
 }
 function PhiWidgetEffectsPreviewFrame({ kind, slotSizePolicy, surfacePolicy, blockId, regionKey, config: committedConfig, title, scaffoldLabel, editorInteraction = "inert", onSelect, dropTarget, tools, style, children, }) {
-    const { token } = usePhiConfig();
+    // The editor's colours, not a tone's: a Widget inside a toned Surface is marked in the page's mode.
+    const token = usePhiPageModeToken();
     const selected = usePhiDeveloperBuilderStateValue((state) => blockId != null &&
         regionKey != null &&
         state.selectedRootRegionKey === regionKey &&
@@ -525,10 +530,6 @@ function PhiLayoutEffectsPreviewFrame({ kind, slotSizePolicy, blockId, config: c
                     });
                 } })) : null] }, hasPreviewEffects ? `layout-effects-preview-${blockId ?? "root"}-${previewRunId}` : undefined));
 }
-function PhiAuthoringLayoutEffectsPreviewFrame({ type, ...props }) {
-    const definition = usePhiAuthoringLayoutDefinition(resolvePhiAuthoringLayoutType(type));
-    return (_jsx(PhiLayoutEffectsPreviewFrame, { ...props, slotSizePolicy: definition?.slotSizePolicy }));
-}
 /**
  * The band under a scaffold: what this node is called, and then what it is.
  *
@@ -821,11 +822,20 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                 nodeKind: normalizedRootNode.kind,
             })
             : undefined, chrome: renderRootScaffoldToolbar(), children: wrapRootScaffoldChild(child) }));
-    const renderChildLayoutNode = (node) => {
+    /*
+     * A nested Layout's frame states its policy on the element the parent Layout sizes its slot by.
+     *
+     * It was looked up inside that element, which is too late: the parent reads the element's props
+     * before it renders, found a Layout with no policy, took the Layout default -- fill both ways -- and
+     * let the slot grow and shrink in its column. A Grid of cards in a Flex was squeezed below its
+     * content on the canvas and the cards ran out of their scaffold, while the page laid it out at its
+     * content height, as its `fill-inline` says.
+     */
+    const renderChildLayoutNodeWith = (resolveLayoutDefinition) => function renderChildLayoutNode(node) {
         const nodeKind = "layout";
         const rootProps = resolveLayoutNodeRootProps(node);
         const rootPropsGeometry = resolvePhiRenderableBlockGeometry(normalizePhiBuilderRootNodeDraft(rootProps).rootNodeGeometry);
-        return (_jsx(PhiAuthoringLayoutEffectsPreviewFrame, { type: node.widgetType, kind: nodeKind, blockId: node.id, config: node.config, explicitInlineSize: rootPropsGeometry.explicitInline, explicitBlockSize: rootPropsGeometry.explicitBlock, children: renderPhiRootNodeScaffold({ ...rootProps, regionKey }, (options) => onOpenInsert?.({
+        return (_jsx(PhiLayoutEffectsPreviewFrame, { kind: nodeKind, slotSizePolicy: resolveLayoutDefinition(resolvePhiAuthoringLayoutType(node.widgetType))?.slotSizePolicy, blockId: node.id, config: node.config, explicitInlineSize: rootPropsGeometry.explicitInline, explicitBlockSize: rootPropsGeometry.explicitBlock, children: renderPhiRootNodeScaffold({ ...rootProps, regionKey }, (options) => onOpenInsert?.({
                 ...options,
                 slotIndex: options?.slotIndex ?? 0,
                 targetNodeId: node.id,
@@ -861,8 +871,8 @@ export function renderPhiRootNodeScaffold(rootNode, onOpenInsert, onOpenInspecto
                 renderInsertPicker: options?.renderInsertPicker,
             }) }));
     };
-    const scaffold = (_jsx(PhiAuthoringLayoutLoader, { type: normalizedRootNode.typeKey, kind: "layout", blockId: normalizedRootNode.id ?? -1, children: (plugin, definition, widgetDefinitionsByType) => {
-            const rendered = resolvePhiRootNodeRenderedBody(normalizedRootNode, "editor", plugin, definition, widgetDefinitionsByType, regionKey, renderChildLayoutNode, onDeleteRootNode
+    const scaffold = (_jsx(PhiAuthoringLayoutLoader, { type: normalizedRootNode.typeKey, kind: "layout", blockId: normalizedRootNode.id ?? -1, children: (plugin, definition, widgetDefinitionsByType, resolveLayoutDefinition) => {
+            const rendered = resolvePhiRootNodeRenderedBody(normalizedRootNode, "editor", plugin, definition, widgetDefinitionsByType, regionKey, renderChildLayoutNodeWith(resolveLayoutDefinition), onDeleteRootNode
                 ? (widget) => onDeleteRootNode({
                     nodeId: widget.id,
                     nodeKey: widget.widgetType,

package/plugins/runtime-modules/builder/trees/phi-default-builder-area-preset-tree.js

@@ -1490,14 +1490,18 @@ async function buildPhiDefaultBuilderPagePresetTemplateTree({ page, runtime, pre
                                         key: "createPage",
                                         emits: [{ capabilityId: "command", value: "createPage" }],
                                         label: labels.pages.newPage,
+                                        tooltip: labels.pages.newPage,
                                         icon: "plus",
+                                        display: "icon",
                                         variant: "primary",
                                     },
                                     {
                                         key: "editPageMeta",
                                         emits: [{ capabilityId: "command", value: "editPageMeta" }],
                                         label: labels.pages.pageMeta,
+                                        tooltip: labels.pages.pageMeta,
                                         icon: "edit",
+                                        display: "icon",
                                     },
                                     {
                                         key: "deletePage",

package/plugins/runtime-modules/builder/widgets/structure-region/built-in.js

@@ -40,6 +40,7 @@ import { PhiTypographyControl } from "../../../../../components/controls/phi-typ
 import { PhiIcon } from "../../../../../components/shell/phi-icon";
 import { PhiSurfaceTone } from "../../../../../components/surface/phi-surface-tone";
 import { resolvePhiSurfaceToneClassName } from "../../../../../types/surface";
+import { PHI_SURFACE_TONE_GROUND, phiSurfaceTakesToneGround } from "../../../../../helpers/surface-style";
 /** The Region's root Layout placed into another tree, at the slot it is moved to. */
 function buildStructureRootLayoutNode(draft, parentLayoutNodeId, slotIndex) {
     if (!draft.rootNode) {
@@ -353,16 +354,26 @@ export function PhiStructureRegionScaffold({ config, serverPreview, structureDra
     const shouldStretchAvailableHeight = shouldFillAvailableHeight || shouldStretchContentRegion;
     const hasExplicitSidebarWidth = isFullHeightRegion && draftGeometry.explicitInline;
     const regionToneClassName = resolvePhiSurfaceToneClassName(effectiveDraft?.surface?.tone);
-    const slotBackgroundStyle = effectiveDraft?.surface?.background
-        ? resolvePhiBackgroundWidgetStyle(effectiveDraft.surface.background)
-        : {};
     /*
      * Whether the author gave this Region a ground. The Builder writes a Background config onto every
      * Region draft it persists, so only a config that paints something counts. An unauthored Region is
      * transparent in the live Shell, and the Canvas keeps that legible: its slot paints a half-transparent
      * container tint, so the Theme Root Background stays visible through it.
      */
-    const hasAuthoredGround = phiBackgroundWidgetConfigPaintsGround(effectiveDraft?.surface?.background ?? null);
+    const paintsAuthoredGround = phiBackgroundWidgetConfigPaintsGround(effectiveDraft?.surface?.background ?? null);
+    /*
+     * A toned Region takes its tone's ground where its Background paints none, by the rule the live Region
+     * shell follows (`phiSurfaceTakesToneGround`). The slot carries the tone's class, so the ground resolves
+     * in the tone's mode; it is a ground of the Region's own, so the Canvas tint does not cover it.
+     */
+    const toneGround = phiSurfaceTakesToneGround(effectiveDraft?.surface?.tone, paintsAuthoredGround);
+    const hasAuthoredGround = paintsAuthoredGround || toneGround;
+    const slotBackgroundStyle = {
+        ...(effectiveDraft?.surface?.background
+            ? resolvePhiBackgroundWidgetStyle(effectiveDraft.surface.background)
+            : {}),
+        ...(toneGround ? { backgroundColor: PHI_SURFACE_TONE_GROUND } : {}),
+    };
     const slotBorderStyle = effectiveDraft?.surface?.border ? resolvePhiBorderWidgetStyle(effectiveDraft.surface.border) : {};
     const regionConfig = (effectiveDraft?.regionConfig ?? null);
     const regionPaddingStyle = resolvePhiPaddingStyle(normalizePhiPaddingWidgetConfig(effectiveDraft?.regionConfig) ?? {});

package/plugins/runtime-modules/client-authoring-module.d.ts

@@ -28,4 +28,11 @@ export declare function createPhiRuntimeModuleAuthoringClient({ moduleId, Widget
     layouts?: readonly PhiAuthoringLayoutModuleLoader[];
 }): ComponentType<PhiRuntimeModuleAuthoringClientProps>;
 export declare function usePhiRuntimeModuleAuthoringRegistration(moduleId: PhiRuntimeModuleId | null | undefined): PhiRuntimeModuleAuthoringRegistration | null;
-export declare function usePhiAuthoringLayoutDefinition(type: string): PhiAuthoringLayoutDefinition | null;
+/**
+ * The authoring Layout definitions, as a lookup by type rather than one type's answer.
+ *
+ * A Layout names its nested Layouts only while it renders its children, and a parent Layout sizes each
+ * slot by the props of the element standing in it, before that element renders: a nested Layout's
+ * element has to carry its policy already, and a hook inside it would be too late.
+ */
+export declare function usePhiAuthoringLayoutDefinitionResolver(): (type: string) => PhiAuthoringLayoutDefinition | null;

package/plugins/runtime-modules/client-authoring-module.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, lazy, useContext, useMemo, } from "react";
+import { createContext, lazy, useCallback, useContext, useMemo, } from "react";
 const PhiRuntimeModuleAuthoringContext = createContext(new Map());
 function createPhiLazyAuthoringLayout(load) {
     return lazy(async () => {
@@ -54,8 +54,7 @@ export function usePhiRuntimeModuleAuthoringRegistration(moduleId) {
     const modules = useContext(PhiRuntimeModuleAuthoringContext);
     return moduleId ? modules.get(moduleId) ?? null : null;
 }
-export function usePhiAuthoringLayoutDefinition(type) {
-    const modules = useContext(PhiRuntimeModuleAuthoringContext);
+function findPhiAuthoringLayoutDefinition(modules, type) {
     for (const registration of modules.values()) {
         const definition = registration.layoutsByType.get(type);
         if (definition) {
@@ -64,3 +63,14 @@ export function usePhiAuthoringLayoutDefinition(type) {
     }
     return null;
 }
+/**
+ * The authoring Layout definitions, as a lookup by type rather than one type's answer.
+ *
+ * A Layout names its nested Layouts only while it renders its children, and a parent Layout sizes each
+ * slot by the props of the element standing in it, before that element renders: a nested Layout's
+ * element has to carry its policy already, and a hook inside it would be too late.
+ */
+export function usePhiAuthoringLayoutDefinitionResolver() {
+    const modules = useContext(PhiRuntimeModuleAuthoringContext);
+    return useCallback((type) => findPhiAuthoringLayoutDefinition(modules, type), [modules]);
+}

package/plugins/runtime-modules/core/widgets/brand/client.d.ts

@@ -11,10 +11,19 @@ export type PhiBrandWidgetConfig = {
 export declare const PHI_BRAND_LINE_FALLBACK_ICONS: Record<PhiBrandWidgetLineMode, string>;
 export type PhiBrandWidgetClientProps = PhiClientBlockBaseProps<PhiNoLabels, PhiBrandWidgetConfig> & {
     fallbackTitle?: ReactNode;
-    /** The language being read, which the way home keeps. */
-    locale?: string;
+    /**
+     * Where the Brand leads, resolved on the Server: the Theme's `homeLinkTarget`, or the Site root in the
+     * language being read. A Page reference means nothing in a browser, so the address travels instead.
+     */
+    home?: PhiBrandWidgetHome;
     interactive?: boolean;
 };
+/** A ready address, and whether it leaves the Site -- the shape `resolvePhiLinkHref` answers. */
+export type PhiBrandWidgetHome = {
+    href: string;
+    newTab: boolean;
+    external: boolean;
+};
 /**
  * The Brand in the Site frame: what `PhiBrandControl` shows, and where clicking it leads.
  *
@@ -22,4 +31,4 @@ export type PhiBrandWidgetClientProps = PhiClientBlockBaseProps<PhiNoLabels, Phi
  * because the Theme workspace preview shows the same Brand without being in a frame and without
  * leading anywhere.
  */
-export declare function PhiBrandWidgetClient({ config, locale, fallbackTitle, interactive, }: PhiBrandWidgetClientProps): import("react").JSX.Element | null;
+export declare function PhiBrandWidgetClient({ config, home, fallbackTitle, interactive, }: PhiBrandWidgetClientProps): import("react").JSX.Element | null;

package/plugins/runtime-modules/core/widgets/brand/client.js

@@ -1,13 +1,12 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import Link from "next/link";
 import { PhiBrandControl, PhiBrandLineControl, phiBrandControlIsEmpty, } from "../../../../../components/controls/phi-brand-control";
 import { isPhiBrandWidgetLineMode, } from "./mode";
 import { usePhiConfig } from "../../../../../components/root/phi-config-provider";
 import { usePhiSiteBrand } from "../../../../../components/root/phi-root-live-theme-provider";
 import { resolvePhiWidgetFontFamily } from "../../../../../components/widgets/helpers/font-family";
 import { resolvePhiWidgetFontSize } from "../../../../../components/widgets/helpers/font-size";
-import { localizePath } from "../../../../../helpers/locale";
+import { PhiLink } from "../../../../../components/navigation/phi-link";
 /** What a line shows in front of itself where the Brand names no icon for it. */
 export const PHI_BRAND_LINE_FALLBACK_ICONS = {
     slogan: "antd:star",
@@ -20,7 +19,7 @@ export const PHI_BRAND_LINE_FALLBACK_ICONS = {
  * because the Theme workspace preview shows the same Brand without being in a frame and without
  * leading anywhere.
  */
-export function PhiBrandWidgetClient({ config, locale, fallbackTitle, interactive = true, }) {
+export function PhiBrandWidgetClient({ config, home, fallbackTitle, interactive = true, }) {
     const brand = usePhiSiteBrand();
     // The Theme's mode, not the Widget's: one picks the Logo's picture, the other what is drawn at all.
     const { fonts, token, mode: themeMode } = usePhiConfig();
@@ -54,13 +53,6 @@ export function PhiBrandWidgetClient({ config, locale, fallbackTitle, interactiv
     if (phiBrandControlIsEmpty(presentation)) {
         return null;
     }
-    /*
-     * The front page in the language being read. `/` alone is answered with a redirect to the visitor's
-     * preferred language, so a reader of `/de` could be led to `/en`; and Next's prefetch of it, which loses
-     * its `_rsc` on that redirect, came back with the static tree's own address and a 404
-     * (AUDIT-2026-10-13, PM15).
-     */
-    const homeHref = brand?.homeHref?.trim() || (locale ? localizePath(locale, "/") : "/");
     const linkStyle = {
         color: "inherit",
         textDecoration: "none",
@@ -73,5 +65,5 @@ export function PhiBrandWidgetClient({ config, locale, fallbackTitle, interactiv
     if (!interactive) {
         return (_jsx("span", { "aria-disabled": "true", style: linkStyle, children: _jsx(PhiBrandControl, { ...presentation }) }));
     }
-    return (_jsx(Link, { href: homeHref, style: linkStyle, children: _jsx(PhiBrandControl, { ...presentation }) }));
+    return (_jsx(PhiLink, { href: home?.href ?? "/", external: home?.external, newTab: home?.newTab, style: linkStyle, children: _jsx(PhiBrandControl, { ...presentation }) }));
 }

package/plugins/runtime-modules/core/widgets/brand/home.d.ts

@@ -0,0 +1,15 @@
+import type { PhiBlockRuntime } from "../../../../../types";
+import { type PhiResolvedLinkTargets } from "../../../../../types/references";
+import type { PhiBrandWidgetHome } from "./client";
+/**
+ * Where the Brand leads, as an address: the Theme's target, resolved in this render's batch of link
+ * targets (`resolvePhiCmsTreeLinkTargets` collects the Brand's beside the tree's), or the Site root.
+ *
+ * The root is the root in the language being read. `/` alone is answered with a redirect to the
+ * visitor's preferred language, so a reader of `/de` could be led to `/en`; and Next's prefetch of it,
+ * which loses its `_rsc` on that redirect, came back with the static tree's own address and a 404
+ * (AUDIT-2026-10-13, PM15). A target that does not resolve -- a Page deleted, unpublished, or brought by
+ * a Module that is switched off -- leads there too: the Brand is the way home and always leads somewhere.
+ * A resolved Page path is already locale- and Area-correct (`REFERENCES.md`).
+ */
+export declare function resolvePhiBrandWidgetHome(runtime: Pick<PhiBlockRuntime, "site" | "locale">, links: PhiResolvedLinkTargets | null | undefined): PhiBrandWidgetHome;

package/plugins/runtime-modules/core/widgets/brand/home.js

@@ -0,0 +1,18 @@
+import { resolvePhiLinkHref } from "../../../../../helpers/link-target";
+import { localizePath } from "../../../../../helpers/locale";
+import { readPhiLinkTarget } from "../../../../../types/references";
+/**
+ * Where the Brand leads, as an address: the Theme's target, resolved in this render's batch of link
+ * targets (`resolvePhiCmsTreeLinkTargets` collects the Brand's beside the tree's), or the Site root.
+ *
+ * The root is the root in the language being read. `/` alone is answered with a redirect to the
+ * visitor's preferred language, so a reader of `/de` could be led to `/en`; and Next's prefetch of it,
+ * which loses its `_rsc` on that redirect, came back with the static tree's own address and a 404
+ * (AUDIT-2026-10-13, PM15). A target that does not resolve -- a Page deleted, unpublished, or brought by
+ * a Module that is switched off -- leads there too: the Brand is the way home and always leads somewhere.
+ * A resolved Page path is already locale- and Area-correct (`REFERENCES.md`).
+ */
+export function resolvePhiBrandWidgetHome(runtime, links) {
+    return resolvePhiLinkHref(readPhiLinkTarget(runtime.site.theme?.brand?.homeLinkTarget), links)
+        ?? { href: localizePath(runtime.locale.current, "/"), newTab: false, external: false };
+}

package/plugins/runtime-modules/core/widgets/brand/plugin.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { resolvePhiBrandWordmarkText } from "../../../../../helpers/brand-wordmark";
+import { resolvePhiBrandWidgetHome } from "./home";
 import { PhiBrandWidget } from "./server";
 import { PHI_BRAND_WIDGET_DEFINITION, PHI_BRAND_WIDGET_PLUGIN_TYPE, } from "./config";
 /*
@@ -13,7 +14,7 @@ import { PHI_BRAND_WIDGET_DEFINITION, PHI_BRAND_WIDGET_PLUGIN_TYPE, } from "./co
  */
 export const PHI_BRAND_WIDGET_PLUGIN = {
     ...PHI_BRAND_WIDGET_DEFINITION,
-    render: ({ widget, config, runtime }) => (_jsx(PhiBrandWidget, { fallbackTitle: resolvePhiBrandWordmarkText(runtime), locale: runtime.locale.current, mode: config.mode, fontFamily: config.fontFamily, fontSize: config.fontSize }, `widget-${widget.id}`)),
-    renderPreview: ({ widget, config, runtime }) => (_jsx(PhiBrandWidget, { fallbackTitle: resolvePhiBrandWordmarkText(runtime), locale: runtime.locale.current, mode: config.mode, fontFamily: config.fontFamily, fontSize: config.fontSize, interactive: false }, `widget-${widget.id}`)),
+    render: ({ widget, config, runtime, links }) => (_jsx(PhiBrandWidget, { fallbackTitle: resolvePhiBrandWordmarkText(runtime), home: resolvePhiBrandWidgetHome(runtime, links), mode: config.mode, fontFamily: config.fontFamily, fontSize: config.fontSize }, `widget-${widget.id}`)),
+    renderPreview: ({ widget, config, runtime, links }) => (_jsx(PhiBrandWidget, { fallbackTitle: resolvePhiBrandWordmarkText(runtime), home: resolvePhiBrandWidgetHome(runtime, links), mode: config.mode, fontFamily: config.fontFamily, fontSize: config.fontSize, interactive: false }, `widget-${widget.id}`)),
 };
 export { PHI_BRAND_WIDGET_PLUGIN_TYPE };

package/plugins/runtime-modules/core/widgets/brand/server.d.ts

@@ -1,3 +1,3 @@
 import type { PhiBrandWidgetClientProps, PhiBrandWidgetConfig } from "./client";
-export type PhiBrandWidgetProps = Pick<PhiBrandWidgetClientProps, "fallbackTitle" | "interactive" | "locale"> & PhiBrandWidgetConfig;
-export declare function PhiBrandWidget({ fallbackTitle, interactive, locale, mode, fontFamily, fontSize, }: PhiBrandWidgetProps): import("react").JSX.Element;
+export type PhiBrandWidgetProps = Pick<PhiBrandWidgetClientProps, "fallbackTitle" | "interactive" | "home"> & PhiBrandWidgetConfig;
+export declare function PhiBrandWidget({ fallbackTitle, interactive, home, mode, fontFamily, fontSize, }: PhiBrandWidgetProps): import("react").JSX.Element;

package/plugins/runtime-modules/core/widgets/brand/server.js

@@ -5,12 +5,12 @@ import { PhiRuntimeModuleRenderClientHost } from "../../../../../components/runt
  * The Brand itself is not read here. It comes from the root on the Client (`usePhiSiteBrand`), which
  * holds it with the Theme Set's Logo folded in and follows a live Theme draft.
  */
-export function PhiBrandWidget({ fallbackTitle, interactive, locale, mode, fontFamily, fontSize, }) {
+export function PhiBrandWidget({ fallbackTitle, interactive, home, mode, fontFamily, fontSize, }) {
     const config = { mode, fontFamily, fontSize };
     return (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiCmsWidgetType.Brand, componentProps: {
             config,
             fallbackTitle,
-            locale,
+            home,
             interactive,
         } }));
 }

package/plugins/runtime-modules/core/widgets/card/config.d.ts

@@ -2,7 +2,7 @@ import type { PhiCmsConfigField } from "../../../../../types/cms-plugins";
 import type { PhiImageAssetVariantKeyValue } from "../../../../../types/media";
 import { type PhiLinkTarget } from "../../../../../types/references";
 import { type PhiBulletListEntry, type PhiBulletListStyle } from "../../../../../components/widgets/shared/bullet-list-vocabulary";
-import { type PhiCardBillingPeriod, type PhiCardHeadingLevel, type PhiCardHoverEffect, type PhiCardIconPlacement, type PhiCardTextAlign, type PhiCardVariant, type PhiCardWidgetBody } from "../../../../../components/widgets/shared/card-vocabulary";
+import { type PhiCardBillingPeriod, type PhiCardHeadingLevel, type PhiCardHoverEffect, type PhiCardIconPlacement, type PhiCardTextAlign, type PhiCardBadgeStyle, type PhiCardVariant, type PhiCardWidgetBody } from "../../../../../components/widgets/shared/card-vocabulary";
 import { type PhiSignalRouteSet } from "../../../../../types/signals";
 import { type PhiCmsWidgetConfigBase } from "../../../../../components/widgets/config/parser-primitives";
 type PhiCardImageSource = {
@@ -27,6 +27,8 @@ export type PhiCmsCardWidgetConfig = PhiCmsWidgetConfigBase & PhiCardImageSource
     badge?: string;
     /** The band's colour; absent, the Theme's primary. */
     badgeColor?: string;
+    /** How the badge is drawn (`PHI_CARD_BADGE_STYLES`); absent, `none`. */
+    badgeStyle?: PhiCardBadgeStyle;
     /** A `plan` body's prices, never translated, and what each is paid per (`/ month`), which is. */
     price?: string;
     pricePeriod?: string;
@@ -106,6 +108,7 @@ export declare const PHI_CARD_WIDGET_DEFINITION: {
         imageOpacity: number;
         headingLevel: "h3";
         textAlign: "start";
+        badgeStyle: "none";
     };
     creationConfig: {
         surface: {
@@ -130,6 +133,7 @@ export declare const PHI_CARD_WIDGET_DEFINITION: {
         imageOpacity: number;
         headingLevel: "h3";
         textAlign: "start";
+        badgeStyle: "none";
     };
     fields: (({
         key: string;
@@ -142,6 +146,7 @@ export declare const PHI_CARD_WIDGET_DEFINITION: {
     } & {
         type: "string" | "url" | "icon";
         emptyValue?: "";
+        placeholder?: string;
     }) | ({
         key: string;
         label: string;

package/plugins/runtime-modules/core/widgets/card/config.js

@@ -4,7 +4,7 @@ import { readPhiLinkTarget } from "../../../../../types/references";
 import { readPhiMediaImageSourceConfig } from "../../../../../components/widgets/config/image-source-parser";
 import { PHI_SURFACE_CARD } from "../../../../../helpers/surface-presets";
 import { buildPhiBulletListFields, readPhiBulletListEntries, readPhiBulletListStyle, } from "../../../../../components/widgets/shared/bullet-list-vocabulary";
-import { PHI_CARD_HEADING_LEVELS, PHI_CARD_HOVER_EFFECTS, PHI_CARD_ICON_PLACEMENTS, PHI_CARD_TEXT_ALIGNS, PHI_CARD_VARIANTS, readPhiCardBillingPeriod, } from "../../../../../components/widgets/shared/card-vocabulary";
+import { PHI_CARD_HEADING_LEVELS, PHI_CARD_HOVER_EFFECTS, PHI_CARD_ICON_PLACEMENTS, PHI_CARD_TEXT_ALIGNS, PHI_CARD_BADGE_STYLES, PHI_CARD_VARIANTS, readPhiCardBillingPeriod, } from "../../../../../components/widgets/shared/card-vocabulary";
 import { readPhiControlLabel } from "../../../../../components/widgets/config/common-action-field";
 import { PHI_CARD_SIGNALS } from "../../../../../components/widgets/signals/control-signal-capabilities";
 import { readPhiSignalRouteSet } from "../../../../../types/signals";
@@ -27,6 +27,7 @@ function parsePhiCmsCardWidgetConfig(config) {
         value: readString(config.value),
         badge: readString(config.badge),
         badgeColor: readString(config.badgeColor),
+        badgeStyle: readChoice(readString(config.badgeStyle), PHI_CARD_BADGE_STYLES),
         price: readString(config.price),
         pricePeriod: readString(config.pricePeriod),
         priceYearly: readString(config.priceYearly),
@@ -68,6 +69,7 @@ const PHI_CARD_DEFAULT_CONFIG = {
     imageOpacity: 100,
     headingLevel: "h3",
     textAlign: "start",
+    badgeStyle: "none",
 };
 export const PHI_CARD_WIDGET_DEFINITION = {
     kind: "widget",
@@ -259,12 +261,26 @@ export const PHI_CARD_WIDGET_DEFINITION = {
             ],
         },
         { key: "highlight", type: "boolean", label: "Highlight" },
-        /* The band's words are written on the card; its colour is the one thing asked here. */
+        /* The band's words are written on the card; how it is drawn and its colour are asked here. */
+        {
+            key: "badgeStyle",
+            type: "choice",
+            heading: "Badge",
+            label: "Style",
+            presentation: "segmented",
+            description: "Corner: a band in the card's top corner. Tag: a rounded mark a little down the edge. Ribbon: hangs over the card's edge with a fold, and needs room beside the card -- a Layout that clips at the card's edge cuts it off. None: hides the badge and keeps its words.",
+            options: [
+                { value: "none", label: "None" },
+                { value: "corner", label: "Corner" },
+                { value: "tag", label: "Tag" },
+                { value: "ribbon", label: "Ribbon" },
+            ],
+        },
         {
             key: "badgeColor",
             type: "color",
-            heading: "Badge",
             label: "Color",
+            visibleWhen: { field: "badgeStyle", notEquals: "none" },
             mode: "single",
             defaultToken: "colorPrimary",
         },

package/plugins/runtime-modules/core/widgets/card/editor.js

@@ -36,7 +36,11 @@ const PHI_CARD_BODY_TEXT_SLOTS = {
  * Slots a card often goes without. Empty, they stand on the canvas only while the card is under the
  * pointer or being written in (`styles/layout.css`), so an empty card does not read as four empty lines.
  */
-const PHI_CARD_OPTIONAL_TEXT_SLOTS = new Set(["eyebrow", "meta", "badge"]);
+/*
+ * Not the badge: it is drawn only once a style is chosen for it, and a band or ribbon that disappeared
+ * whenever the pointer left the card left nothing to see of the choice just made.
+ */
+const PHI_CARD_OPTIONAL_TEXT_SLOTS = new Set(["eyebrow", "meta"]);
 /**
  * One of the card's words, edited where it stands: underlined, in the type of the text it edits.
  *
@@ -55,7 +59,12 @@ function PhiCardInlineText({ slot, text, onCommit, }) {
          * into beside them, and its wrapping is the card's own anyway. The text still wraps and aligns as
          * the card sets it.
          */
-        style: { width: "100%" }, 
+        /*
+         * The ground stays the card's, here as well as on the text: with a clear button the field is a
+         * wrapper around the text, and Ant Design's underlined wrapper paints the container ground -- white
+         * over the badge's band, whose light words then vanished on it.
+         */
+        style: { width: "100%", backgroundColor: "transparent" }, 
         /* The text's own type, and the page showing through: an edit in place reads like what it edits. */
         inputStyle: {
             paddingInline: 0,
@@ -116,7 +125,7 @@ export function PhiCardWidgetEditor({ config, onChange }) {
         && presentation.width != null
         && canvasWidth != null
         && presentation.width < canvasWidth;
-    return (_jsxs("div", { ref: canvasRef, className: "phi-card-editor", style: { position: "relative", width: "100%" }, children: [_jsx(PhiCardWidgetClient, { labels: {
+    return (_jsxs("div", { ref: canvasRef, className: "phi-card-editor", style: { position: "relative", display: "flex", width: "100%" }, children: [_jsx(PhiCardWidgetClient, { labels: {
                     eyebrow: config.eyebrow,
                     title: config.title,
                     description: config.description,
@@ -165,6 +174,7 @@ export function PhiCardWidgetEditor({ config, onChange }) {
                     body: config.body,
                     highlight: config.highlight,
                     badgeColor: config.badgeColor,
+                    badgeStyle: config.badgeStyle,
                     billingPeriod: config.billingPeriod,
                     hoverEffect: config.linkTarget ? config.hoverEffect : undefined,
                 }, ...(config.body === "plan" ? {

package/plugins/runtime-modules/core/widgets/card/server.js

@@ -113,6 +113,7 @@ export async function PhiCardWidget({ labels, config, runtime, links, translate,
         body: config?.body,
         highlight: config?.highlight,
         badgeColor: config?.badgeColor,
+        badgeStyle: config?.badgeStyle,
         billingPeriod: config?.billingPeriod,
         // Only a card that leads somewhere answers the pointer; the preview has no link but shows it.
         hoverEffect: config?.linkTarget ? config.hoverEffect : undefined,

package/plugins/runtime-modules/core/widgets/description/client.js

@@ -8,7 +8,6 @@ import { PhiBulletListControl } from "../../../../../components/controls/phi-bul
 import { buildPhiBulletListTree, resolvePhiBulletListStyle, } from "../../../../../components/widgets/shared/bullet-list-vocabulary";
 import { resolvePhiTextPlaceholders } from "../../../../../helpers/text-placeholders";
 const PHI_LINE_HEIGHT_BASE = 1.5;
-const PHI_LINE_HEIGHT_LG = 1.6;
 const PHI_FONT_WEIGHT_STRONG = 600;
 export function PhiDescriptionWidgetClient({ labels, config, }) {
     const { token } = usePhiConfig();
@@ -18,6 +17,7 @@ export function PhiDescriptionWidgetClient({ labels, config, }) {
                     borderRadius: 999,
                     paddingInline: token.paddingSM,
                     paddingBlock: token.paddingXXS,
+                    fontSize: token.fontSizeSM,
                     fontWeight: PHI_FONT_WEIGHT_STRONG,
                     letterSpacing: "0.04em",
                     color: token.colorTextTertiary,
@@ -26,8 +26,8 @@ export function PhiDescriptionWidgetClient({ labels, config, }) {
                 }, children: labels.eyebrow })) : null, labels.title || labels.description ? (_jsxs("div", { children: [labels.title ? (_jsx(PhiTypographyControl, { presentation: "title", level: 2, style: { marginBottom: labels.description ? token.paddingXS : 0 }, children: labels.title })) : null, labels.description ? (_jsx(PhiTypographyControl, { presentation: "paragraph", type: config?.tone, style: {
                             marginBottom: 0,
                             color: config?.tone ? undefined : token.colorTextSecondary,
-                            fontSize: token.fontSizeLG,
-                            lineHeight: PHI_LINE_HEIGHT_LG,
+                            fontSize: token.fontSize,
+                            lineHeight: PHI_LINE_HEIGHT_BASE,
                         }, children: labels.description })) : null] })) : null, labels.asideTitle || asideItems.length > 0 ? (_jsxs(PhiFlexControl, { vertical: true, gap: token.paddingMD, style: { width: "100%" }, children: [labels.asideTitle ? (_jsx(PhiTypographyControl, { strong: true, style: {
                             fontSize: token.fontSize,
                             lineHeight: PHI_LINE_HEIGHT_BASE,

package/plugins/runtime-modules/core/widgets/description/config.d.ts

@@ -39,6 +39,7 @@ export declare const PHI_DESCRIPTION_WIDGET_DEFINITION: {
     } & {
         type: "string" | "url" | "icon";
         emptyValue?: "";
+        placeholder?: string;
     }) | ({
         key: string;
         label: string;

package/plugins/runtime-modules/core/widgets/description/editor.js

@@ -60,6 +60,7 @@ export function PhiDescriptionWidgetEditor({ config, onChange, }) {
                         borderRadius: 999,
                         paddingInline: "var(--ant-padding-sm)",
                         paddingBlock: "var(--ant-padding-xxs)",
+                        fontSize: "var(--ant-font-size-sm)",
                         fontWeight: 600,
                         letterSpacing: "0.04em",
                         color: "var(--ant-color-text-tertiary)",
@@ -74,8 +75,8 @@ export function PhiDescriptionWidgetEditor({ config, onChange, }) {
                             } }), _jsx(PhiTextControl, { presentation: "textarea", value: draft.description, readOnly: !onChange, variant: "borderless", placeholder: "Description", autoSize: { minRows: 2, maxRows: 8 }, onChange: (value) => updateField("description", value ?? ""), onBlur: () => commitField("description"), style: {
                                 ...EDITOR_TEXTAREA_STYLE,
                                 color: "var(--ant-color-text-secondary)",
-                                fontSize: "1.125rem",
-                                lineHeight: 1.6,
+                                fontSize: "var(--ant-font-size)",
+                                lineHeight: 1.5,
                             } })] })) : null, sections.aside ? (_jsxs(PhiFlexControl, { vertical: true, gap: 12, style: { width: "100%" }, children: [_jsx(PhiTextControl, { presentation: "textarea", value: draft.asideTitle, readOnly: !onChange, variant: "borderless", placeholder: "Aside title", autoSize: { minRows: 1, maxRows: 3 }, onChange: (value) => updateField("asideTitle", value ?? ""), onBlur: () => commitField("asideTitle"), style: {
                                 ...EDITOR_TEXTAREA_STYLE,
                                 color: "var(--ant-color-text-heading)",

package/plugins/runtime-modules/core/widgets/description/server.js

@@ -64,6 +64,7 @@ export async function PhiDescriptionWidget({ labels, config, runtime, translate,
                     borderRadius: "9999px",
                     paddingInline: PHI_SPACE.sm,
                     paddingBlock: PHI_SPACE.xxs,
+                    fontSize: PHI_FONT_SIZE.sm,
                     fontWeight: 600,
                     letterSpacing: "0.04em",
                     color: PHI_COLOR.textTertiary,
@@ -82,8 +83,8 @@ export async function PhiDescriptionWidget({ labels, config, runtime, translate,
                             margin: 0,
                             marginBottom: 0,
                             color: resolveDescriptionToneColor(config?.tone),
-                            fontSize: PHI_FONT_SIZE.lg,
-                            lineHeight: PHI_LINE_HEIGHT.lg,
+                            fontSize: PHI_FONT_SIZE.base,
+                            lineHeight: PHI_LINE_HEIGHT.base,
                         }, children: description })) : null] })) : null, asideTitle || resolvedAsideItems.length > 0 ? (_jsxs("div", { style: subStackStyle, children: [asideTitle ? (_jsx("span", { style: {
                             display: "block",
                             fontSize: PHI_FONT_SIZE.base,

package/plugins/runtime-modules/core/widgets/entry-list/config.d.ts

@@ -83,6 +83,7 @@ export declare const PHI_ENTRY_LIST_WIDGET_DEFINITION: {
     } & {
         type: "string" | "url" | "icon";
         emptyValue?: "";
+        placeholder?: string;
     }) | ({
         key: string;
         label: string;

package/plugins/runtime-modules/core/widgets/gallery/config.d.ts

@@ -45,6 +45,7 @@ export declare const PHI_GALLERY_WIDGET_DEFINITION: {
     } & {
         type: "string" | "url" | "icon";
         emptyValue?: "";
+        placeholder?: string;
     }) | ({
         key: string;
         label: string;