@phis/ui 0.2.1 → 0.4.0

package/plugins/runtime-modules/builder/clients/inspector-image-field.d.ts

@@ -0,0 +1,17 @@
+import type { PhiCmsInstanceId } from "../../../../types/cms-instance-id";
+/**
+ * A Widget's picture, chosen and described in one place: which picture, in which rendition, and what it
+ * says to a reader who cannot see it. The picture is chosen with the house's media picker, the one the
+ * Background control uses; this adds only what a picture placed on its own also needs.
+ *
+ * It writes the keys every image source is read from (`readPhiMediaImageSourceConfig`) -- `sourceKind`,
+ * `assetId`, `variantKey`, `variantVersion`, `sourceUrl` -- and `alt`. An Asset is picked from the media
+ * library; without one, an address stands for a picture from elsewhere. Removing the picture clears both,
+ * so nothing of the old one is left to come back.
+ */
+export declare function PhiInspectorImageFieldControl({ config, blockId, disabled, onChange, }: {
+    config: Record<string, unknown>;
+    blockId?: PhiCmsInstanceId | null;
+    disabled?: boolean;
+    onChange?: (patch: Record<string, unknown>) => void;
+}): import("react").JSX.Element;

package/plugins/runtime-modules/builder/clients/inspector-image-field.js

@@ -0,0 +1,59 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PhiFlexControl } from "../../../../components/controls/phi-flex-control";
+import { PhiSelectControl } from "../../../../components/controls/phi-select-control";
+import { PhiTextControl } from "../../../../components/controls/phi-text-control";
+import { PhiMediaPickerBinding } from "../../../../components/media/phi-media-picker-binding";
+import { PHI_MEDIA_WIDGET_DEFAULT_LABELS } from "../../../../components/media/media-widget-labels";
+import { createPhiMediaPickerAssetControllerRoutes } from "../../../../components/media/asset-controller-routes";
+import { PHI_SEARCH_WIDGET_DEFAULT_LABELS } from "../../../../components/widgets/label-types/search";
+import { PHI_IMAGE_VARIANT_OPTIONS } from "../../../../components/widgets/config/image-variant-options";
+import { PhiInspectorFieldRow } from "../../../../components/widgets/inspector-field-row";
+import { usePhiAuthoringAssetDetails } from "../../../../components/media/use-authoring-asset-details";
+import { PhiImageAssetVariantKey, PhiMediaKind } from "../../../../constants/media";
+const PHI_IMAGE_FIELD_ORIGINAL_VARIANT = "__original__";
+/**
+ * A Widget's picture, chosen and described in one place: which picture, in which rendition, and what it
+ * says to a reader who cannot see it. The picture is chosen with the house's media picker, the one the
+ * Background control uses; this adds only what a picture placed on its own also needs.
+ *
+ * It writes the keys every image source is read from (`readPhiMediaImageSourceConfig`) -- `sourceKind`,
+ * `assetId`, `variantKey`, `variantVersion`, `sourceUrl` -- and `alt`. An Asset is picked from the media
+ * library; without one, an address stands for a picture from elsewhere. Removing the picture clears both,
+ * so nothing of the old one is left to come back.
+ */
+export function PhiInspectorImageFieldControl({ config, blockId, disabled, onChange, }) {
+    const assetId = config.sourceKind === "asset" && typeof config.assetId === "number" ? config.assetId : null;
+    const asset = usePhiAuthoringAssetDetails(assetId);
+    const sourceUrl = typeof config.sourceUrl === "string" ? config.sourceUrl : "";
+    const variantKey = typeof config.variantKey === "number" ? config.variantKey : PHI_IMAGE_FIELD_ORIGINAL_VARIANT;
+    const editable = !disabled && onChange != null;
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiMediaPickerBinding, { config: {
+                    mediaType: PhiMediaKind.Image,
+                    pageSize: 12,
+                    showPagination: true,
+                    showGroupFilter: true,
+                    showSearchBar: true,
+                    signalRoutes: createPhiMediaPickerAssetControllerRoutes(`inspector-image-${blockId ?? "field"}`, "area"),
+                }, labels: PHI_MEDIA_WIDGET_DEFAULT_LABELS, searchLabels: PHI_SEARCH_WIDGET_DEFAULT_LABELS, value: assetId, onAssetSelect: editable
+                    ? (picked) => onChange?.({
+                        sourceKind: "asset",
+                        assetId: picked.id,
+                        variantKey: PhiImageAssetVariantKey.Card,
+                        variantVersion: picked.variantVersion ?? null,
+                        sourceUrl: undefined,
+                    })
+                    : undefined, onAssetClear: editable
+                    ? () => onChange?.({
+                        sourceKind: "url",
+                        assetId: undefined,
+                        variantKey: undefined,
+                        variantVersion: undefined,
+                        sourceUrl: undefined,
+                    })
+                    : undefined }), assetId != null ? (_jsx(PhiInspectorFieldRow, { label: "Variant", children: _jsx(PhiSelectControl, { value: variantKey, options: [{ value: PHI_IMAGE_FIELD_ORIGINAL_VARIANT, label: "Original", separator: "after" }, ...PHI_IMAGE_VARIANT_OPTIONS], disabled: !editable, style: { width: "100%" }, onChange: (next) => onChange?.({
+                        variantKey: next === PHI_IMAGE_FIELD_ORIGINAL_VARIANT ? null : next,
+                    }) }) })) : (_jsx(PhiInspectorFieldRow, { label: "URL", children: _jsx(PhiTextControl, { value: sourceUrl, inputType: "url", placeholder: "https://", disabled: !editable, style: { width: "100%" }, onChange: (next) => onChange?.({ sourceKind: "url", sourceUrl: next?.trim() || undefined }) }) })), _jsx(PhiInspectorFieldRow, { label: "Alt text", children: _jsx(PhiTextControl, { value: typeof config.alt === "string" ? config.alt : "", 
+                    /* An Asset brings its own; this replaces it for this placement only. */
+                    placeholder: asset?.altText ?? undefined, disabled: !editable, style: { width: "100%" }, onChange: (next) => onChange?.({ alt: next || undefined }) }) })] }));
+}

package/plugins/runtime-modules/builder/clients/inspector-link-target-field.d.ts

@@ -1,30 +1,16 @@
-import { type PhiLinkTarget } from "../../../../types/references";
-export type PhiInspectorLinkTargetLabels = {
-    none: string;
-    page: string;
-    external: string;
-    pagePlaceholder: string;
-    externalPlaceholder: string;
-    newTab: string;
-};
-export declare const PHI_INSPECTOR_LINK_TARGET_DEFAULT_LABELS: PhiInspectorLinkTargetLabels;
+import type { PhiLinkTarget } from "../../../../types/references";
+import { type PhiInspectorLinkTargetLabels } from "../../../../components/widgets/label-types/inspector";
 /**
- * One link, chosen rather than typed, with the two answers it may have kept apart.
- *
- * **The mode is held here and the value is not.** A target is written only once it is one: a Page with
- * nothing picked yet and a half-typed address are both states somebody is passing through, and storing
- * them would put a target in the tree that resolves to nothing, index a reference that is not one, and
- * draw a dead link on the page between two keystrokes. So the segmented control remembers what the
- * author is answering, and the config gets a value when the answer is complete -- or `undefined`, which
- * is a Widget with no link at all.
- *
- * Switching modes drops what the other one held rather than keeping it aside. A hidden address that
- * returns when somebody flips back is a value nobody can see and nobody agreed to, and `REFERENCES.md`
- * has no shape for a target that is two things at once.
+ * The Inspector's link field: the shared link control (`phi-link-target-control.tsx`), offered the Pages
+ * of the Area the Builder is working on.
  */
 export declare function PhiInspectorLinkTargetFieldControl({ value, disabled, labels, onChange, }: {
     value: unknown;
     disabled?: boolean;
     labels?: PhiInspectorLinkTargetLabels;
-    onChange?: (next: PhiLinkTarget | undefined) => void;
+    /**
+     * The target as it now stands. `none` is set when the author answered "None" -- the link is gone, not
+     * only incomplete -- so what depends on a link can go with it.
+     */
+    onChange?: (next: PhiLinkTarget | undefined, none?: boolean) => void;
 }): import("react").JSX.Element;

package/plugins/runtime-modules/builder/clients/inspector-link-target-field.js

@@ -1,69 +1,22 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useState } from "react";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
 import { PhiFlexControl } from "../../../../components/controls/phi-flex-control";
-import { PhiSegmentedControl } from "../../../../components/controls/phi-segmented-control";
-import { PhiSwitchControl } from "../../../../components/controls/phi-switch-control";
-import { PhiTextControl } from "../../../../components/controls/phi-text-control";
-import { PhiTreeSelectControl } from "../../../../components/controls/phi-tree-select-control";
-import { isPhiStorableExternalHref, readPhiLinkTarget, } from "../../../../types/references";
-import { buildPhiBuilderPageReferenceTree } from "../page-reference-tree";
+import { PhiInspectorFieldRow } from "../../../../components/widgets/inspector-field-row";
+import { PhiLinkTargetControl } from "../../../../components/widgets/client/shared/phi-link-target-control";
+import { buildPhiBuilderPageReferenceTree } from "../../../../helpers/page-reference-tree";
 import { usePhiBuilderOfferedPageCatalog } from "../use-offered-page-catalog";
 import { usePhiDeveloperBuilderStateValue } from "../developer-workspace-store";
-export const PHI_INSPECTOR_LINK_TARGET_DEFAULT_LABELS = {
-    none: "None",
-    page: "Page",
-    external: "Address",
-    pagePlaceholder: "Select Page",
-    externalPlaceholder: "https://",
-    newTab: "Open in a new tab",
-};
+import { PHI_INSPECTOR_WIDGET_DEFAULT_LABELS, } from "../../../../components/widgets/label-types/inspector";
 /**
- * One link, chosen rather than typed, with the two answers it may have kept apart.
- *
- * **The mode is held here and the value is not.** A target is written only once it is one: a Page with
- * nothing picked yet and a half-typed address are both states somebody is passing through, and storing
- * them would put a target in the tree that resolves to nothing, index a reference that is not one, and
- * draw a dead link on the page between two keystrokes. So the segmented control remembers what the
- * author is answering, and the config gets a value when the answer is complete -- or `undefined`, which
- * is a Widget with no link at all.
- *
- * Switching modes drops what the other one held rather than keeping it aside. A hidden address that
- * returns when somebody flips back is a value nobody can see and nobody agreed to, and `REFERENCES.md`
- * has no shape for a target that is two things at once.
+ * The Inspector's link field: the shared link control (`phi-link-target-control.tsx`), offered the Pages
+ * of the Area the Builder is working on.
  */
-export function PhiInspectorLinkTargetFieldControl({ value, disabled, labels = PHI_INSPECTOR_LINK_TARGET_DEFAULT_LABELS, onChange, }) {
-    const target = readPhiLinkTarget(value);
-    const [mode, setMode] = useState(target?.kind ?? "none");
-    /*
-     * The address as it is being typed, which the stored value cannot be: a target is only written when
-     * it is storable, so reading the box back out of config would erase every character before the first
-     * one that makes a whole address.
-     */
-    const [draftHref, setDraftHref] = useState(target?.kind === "external" ? target.href : "");
+export function PhiInspectorLinkTargetFieldControl({ value, disabled, labels = PHI_INSPECTOR_WIDGET_DEFAULT_LABELS.fields.linkTarget, onChange, }) {
     const state = usePhiDeveloperBuilderStateValue("public", (current) => current);
     const pages = usePhiBuilderOfferedPageCatalog(state, state.area);
-    const options = useMemo(() => buildPhiBuilderPageReferenceTree(state.area, pages, pages), [pages, state.area]);
-    const newTab = target?.newTab === true;
-    const withNewTab = (next) => (newTab ? { ...next, newTab: true } : next);
-    const changeMode = (nextMode) => {
-        setMode(nextMode);
-        setDraftHref("");
-        onChange?.(undefined);
-    };
-    return (_jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiSegmentedControl, { value: mode, block: true, disabled: disabled || !onChange, options: [
-                    { value: "none", label: labels.none },
-                    { value: "page", label: labels.page },
-                    { value: "external", label: labels.external },
-                ], onChange: changeMode }), mode === "page" ? (_jsx(PhiTreeSelectControl, { value: target?.kind === "page" ? target.reference : null, options: options, placeholder: labels.pagePlaceholder, disabled: disabled || !onChange, allowClear: true, style: { width: "100%" }, onChange: (nextValue) => onChange?.(nextValue
-                    ? withNewTab({ kind: "page", reference: nextValue })
-                    : undefined) })) : null, mode === "external" ? (_jsx(PhiTextControl, { value: draftHref, inputType: "url", placeholder: labels.externalPlaceholder, disabled: disabled || !onChange, style: { width: "100%" }, onChange: (nextValue) => {
-                    const href = nextValue ?? "";
-                    setDraftHref(href);
-                    onChange?.(isPhiStorableExternalHref(href)
-                        ? withNewTab({ kind: "external", href: href.trim() })
-                        : undefined);
-                } })) : null, target ? (_jsx(PhiSwitchControl, { checked: newTab, label: labels.newTab, disabled: disabled || !onChange, onChange: (checked) => onChange?.(checked
-                    ? { ...target, newTab: true }
-                    : { ...target, newTab: undefined }) })) : null] }));
+    const options = useMemo(() => buildPhiBuilderPageReferenceTree(state.area, pages, pages, { landing: labels.landingPage }), [labels.landingPage, pages, state.area]);
+    return (_jsx(PhiLinkTargetControl, { value: value, options: options, labels: labels, disabled: disabled, onChange: onChange, 
+        // A row like every switch in the Inspector: its words on the left, the switch in the control column.
+        newTabRow: (control) => (_jsx(PhiInspectorFieldRow, { label: labels.newTab, children: _jsx(PhiFlexControl, { align: "center", style: { minHeight: "var(--ant-control-height)" }, children: control }) })) }));
 }

package/plugins/runtime-modules/builder/clients/inspector-section-widget.d.ts

@@ -6,6 +6,8 @@ import type { PhiPaddingWidgetLabels } from "../../../../components/widgets/labe
 import type { PhiColorPickerLabels } from "../../../../components/widgets/label-types/color-picker";
 import type { PhiIconPickerControlLabels } from "../../../../components/widgets/label-types/icon-picker";
 import type { PhiSignalsWidgetLabels } from "../../../../components/widgets/label-types/signals";
+import type { PhiInspectorSurfaceLabels } from "./inspector-surface-labels";
+import type { PhiInspectorWidgetLabels } from "../../../../components/widgets/label-types/inspector";
 type PhiBuilderInspectorSectionWidgetClientProps = {
     section?: string;
     signalRoutes?: PhiSignalRouteSet;
@@ -14,10 +16,14 @@ type PhiBuilderInspectorSectionWidgetClientProps = {
     paddingLabels?: PhiPaddingWidgetLabels;
     backgroundLabels?: PhiBackgroundWidgetLabels;
     borderLabels?: PhiBorderWidgetLabels;
+    surfaceLabels?: PhiInspectorSurfaceLabels;
+    gridLabels?: PhiInspectorWidgetLabels["grid"];
+    fieldLabels?: PhiInspectorWidgetLabels["fields"];
+    visibilityLabels?: PhiInspectorWidgetLabels["regionVisibility"];
     colorPickerLabels?: PhiColorPickerLabels;
     iconPickerLabels?: PhiIconPickerControlLabels;
 };
-export declare function PhiBuilderRegionInspectorSectionWidgetClient({ section, signalRoutes, geometryLabels, paddingLabels, backgroundLabels, borderLabels, colorPickerLabels, }: PhiBuilderInspectorSectionWidgetClientProps): import("react").JSX.Element;
-export declare function PhiBuilderLayoutInspectorSectionWidgetClient({ section, signalRoutes, signalsLabels, paddingLabels, backgroundLabels, borderLabels, colorPickerLabels, iconPickerLabels, }: PhiBuilderInspectorSectionWidgetClientProps): import("react").JSX.Element;
-export declare function PhiBuilderWidgetInspectorSectionWidgetClient({ section, signalRoutes, geometryLabels, signalsLabels, colorPickerLabels, iconPickerLabels, }: PhiBuilderInspectorSectionWidgetClientProps): import("react").JSX.Element;
+export declare function PhiBuilderRegionInspectorSectionWidgetClient({ section, signalRoutes, visibilityLabels, geometryLabels, paddingLabels, backgroundLabels, borderLabels, surfaceLabels, colorPickerLabels, }: PhiBuilderInspectorSectionWidgetClientProps): import("react").JSX.Element;
+export declare function PhiBuilderLayoutInspectorSectionWidgetClient({ section, signalRoutes, signalsLabels, paddingLabels, backgroundLabels, borderLabels, surfaceLabels, gridLabels, fieldLabels, colorPickerLabels, iconPickerLabels, }: PhiBuilderInspectorSectionWidgetClientProps): import("react").JSX.Element;
+export declare function PhiBuilderWidgetInspectorSectionWidgetClient({ section, signalRoutes, geometryLabels, surfaceLabels, backgroundLabels, borderLabels, signalsLabels, fieldLabels, colorPickerLabels, iconPickerLabels, }: PhiBuilderInspectorSectionWidgetClientProps): import("react").JSX.Element;
 export {};

package/plugins/runtime-modules/builder/clients/inspector-section-widget.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback } from "react";
+import { useCallback, useMemo } from "react";
 import { PhiMediaPickerBinding } from "../../../../components/media/phi-media-picker-binding";
 import { PHI_MEDIA_WIDGET_DEFAULT_LABELS } from "../../../../components/media/media-widget-labels";
 import { PHI_SEARCH_WIDGET_DEFAULT_LABELS } from "../../../../components/widgets/label-types/search";
@@ -15,12 +15,10 @@ import { isPhiBuilderPageScopedRegion } from "../region-keys";
 import { PhiDeveloperBuilderRegionInspectorWidgetClient } from "./region-inspector";
 import { PhiDeveloperBuilderLayoutInspectorWidgetClient } from "./layout-inspector";
 import { PhiDeveloperBuilderWidgetInspectorWidgetClient } from "./widget-inspector";
-import { readPhiShadow } from "../../../../types/layout-style";
-import { mergePhiCmsConfigValues } from "../../../../types/cms-config";
+import { readPhiSurface } from "../../../../types/surface";
 import { normalizePhiPaddingWidgetConfig } from "../../../../types/cms-config";
-import { resolvePhiBuilderRootNodeDefaultsFromConfig, } from "../root-node-normalization";
 import { usePhiBuilderModuleMetas, } from "../plugin-meta-store";
-import { findPhiBuilderLayoutNodeById, findPhiBuilderWidgetNodeByIdInLayouts, findPhiBuilderWidgetNodeByIdInWidgets, } from "../node-finders";
+import { findPhiBuilderLayoutNodeById, findPhiBuilderWidgetNodeByIdInLayouts, } from "../node-finders";
 import { createPhiMediaPickerAssetControllerRoutes } from "../../../../components/media/asset-controller-routes";
 const PHI_BUILDER_BACKGROUND_MEDIA_ROUTES = {
     preview: createPhiMediaPickerAssetControllerRoutes("builder-background-preview-media", "area"),
@@ -49,87 +47,32 @@ function collectWidgetReferenceOptionsFromDrafts(drafts, area, pageKey) {
         if (!draftKey.startsWith(draftKeyPrefix) || !draftKey.includes(pageDraftKeySegment)) {
             continue;
         }
-        if (draft.rootNodeKind === "widget" && draft.rootNodeId != null && draft.rootNodeTypeKey) {
-            options.push({
-                value: String(draft.rootNodeId),
-                label: draft.rootNodeTitle?.trim() || `Widget ${draft.rootNodeId}`,
-                widgetType: draft.rootNodeTypeKey,
-            });
-        }
-        collectWidgetReferenceOptionsFromWidgets(draft.rootNodeChildWidgets, options);
-        collectWidgetReferenceOptionsFromLayouts(draft.rootNodeChildLayouts, options);
+        collectWidgetReferenceOptionsFromLayouts(draft.rootNode ? [draft.rootNode] : [], options);
     }
     return options;
 }
 /**
- * The Inspector's draft for a root node, from its parsed config and what the node already knows about
- * itself. Whatever `known` carries wins over what the config says; absent, the config and the node
- * kind's defaults answer.
+ * The Inspector's view of a Layout node -- the Region's root Layout or one nested in it, read the same
+ * way: its config over its Layout's defaults, and what the Inspector reads off that config.
  */
-function resolveDraftFromRootConfig(parsedConfig, known) {
-    const rootNodeDefaults = resolvePhiBuilderRootNodeDefaultsFromConfig(parsedConfig);
-    return {
-        ...parsedConfig,
-        ...(known.rootNodeGeometry ?? {}),
-        rootNodeId: known.rootNodeId,
-        rootNodeTypeKey: known.rootNodeTypeKey,
-        rootNodeKind: known.rootNodeKind,
-        rootNodeTitle: known.rootNodeTitle,
-        rootNodeAnchor: known.rootNodeAnchor,
-        rootNodePadding: mergePhiCmsConfigValues(rootNodeDefaults.rootNodePadding, known.rootNodePadding ?? normalizePhiPaddingWidgetConfig(parsedConfig)),
-        rootNodeBackground: known.rootNodeBackground ??
-            (typeof parsedConfig.background === "object" && parsedConfig.background != null
-                ? parsedConfig.background
-                : rootNodeDefaults.rootNodeBackground),
-        rootNodeBorder: known.rootNodeBorder ??
-            (typeof parsedConfig.border === "object" && parsedConfig.border != null
-                ? parsedConfig.border
-                : rootNodeDefaults.rootNodeBorder),
-        rootNodeShadow: known.rootNodeShadow ??
-            readPhiShadow(parsedConfig.rootNodeShadow) ?? null,
-    };
-}
 function resolveDraftFromLayoutNode(node, meta) {
     if (!node) {
         return null;
     }
-    const parsedConfig = {
+    const config = {
         ...(meta?.defaultConfig ?? {}),
         ...(node.config ?? {}),
     };
-    return resolveDraftFromRootConfig(parsedConfig, {
-        rootNodeId: node.id,
-        rootNodeTypeKey: node.widgetType,
-        rootNodeKind: "layout",
-        rootNodeTitle: node.label,
+    return {
+        node,
+        config,
         // A stored placement name is taken as it is; only an anchor object is resolved.
-        rootNodeAnchor: (typeof parsedConfig.anchor === "string" && isPhiAnchorWidgetPlacement(parsedConfig.anchor)
-            ? parsedConfig.anchor
-            : resolvePhiAnchorPlacement(parsedConfig.anchor)) ?? null,
-    });
-}
-function resolveDraftFromRootNodeDraft(draft, meta) {
-    if (!draft) {
-        return null;
-    }
-    const parsedRootConfig = {
-        ...(meta?.defaultConfig ?? {}),
-        ...(draft.rootNodeConfig ?? draft),
+        anchor: (typeof config.anchor === "string" && isPhiAnchorWidgetPlacement(config.anchor)
+            ? config.anchor
+            : resolvePhiAnchorPlacement(config.anchor)) ?? null,
+        padding: normalizePhiPaddingWidgetConfig(config),
+        surface: readPhiSurface(config.surface),
     };
-    return resolveDraftFromRootConfig(parsedRootConfig, {
-        rootNodeGeometry: draft.rootNodeGeometry,
-        rootNodeId: draft.rootNodeId ?? null,
-        rootNodeTypeKey: draft.rootNodeTypeKey ?? null,
-        rootNodeKind: draft.rootNodeKind ?? null,
-        rootNodeTitle: draft.rootNodeTitle ?? null,
-        rootNodeAnchor: draft.rootNodeAnchor ??
-            resolvePhiAnchorPlacement(parsedRootConfig.anchor) ??
-            null,
-        rootNodePadding: draft.rootNodePadding,
-        rootNodeBackground: draft.rootNodeBackground,
-        rootNodeBorder: draft.rootNodeBorder,
-        rootNodeShadow: draft.rootNodeShadow,
-    });
 }
 function usePhiBuilderInspectorSectionState(signalRoutes) {
     const dispatchSignal = usePhiSignalDispatcher();
@@ -146,41 +89,37 @@ function usePhiBuilderInspectorSectionState(signalRoutes) {
     const activeDataProviderDescriptors = activeModuleMetas.dataProviders;
     const activeCalendarAdapterDescriptors = activeModuleMetas.calendarAdapters;
     const activeVideoProviderDescriptors = activeModuleMetas.videoProviders;
+    /*
+     * Every Inspector section runs this hook, so what it works out per render is worked out fifteen
+     * times. The lookups and the two tree searches are kept until the drafts or the selection move; the
+     * draft map itself is still subscribed to as a whole, because the reference options below read every
+     * draft of the page.
+     */
     const regionDrafts = usePhiDeveloperRegionDrafts();
     const selectedRegionKey = nodeKind === "region" ? nodeKey.replace(/^region:/, "") : null;
-    const currentRegionDraft = selectedRegionKey
-        ? resolveRegionDraftKey(regionDrafts, area, selectedRegionKey, pageKey)
-        : null;
-    const selectedRootDraft = selectedRootRegionKey
-        ? resolveRegionDraftKey(regionDrafts, area, selectedRootRegionKey, pageKey)
-        : null;
-    const selectedRootNodeId = selectedRootDraft?.rootNodeId ?? null;
-    const selectedNestedLayoutNode = selectedRootDraft && nodeId != null && nodeId !== selectedRootNodeId
-        ? findPhiBuilderLayoutNodeById(selectedRootDraft.rootNodeChildLayouts ?? [], nodeId)
-        : null;
-    const selectedWidgetNode = selectedRootDraft && nodeId != null
-        ? findPhiBuilderWidgetNodeByIdInWidgets(selectedRootDraft.rootNodeChildWidgets ?? [], nodeId) ??
-            findPhiBuilderWidgetNodeByIdInLayouts(selectedRootDraft.rootNodeChildLayouts ?? [], nodeId)
-        : null;
+    const currentRegionDraft = useMemo(() => selectedRegionKey ? resolveRegionDraftKey(regionDrafts, area, selectedRegionKey, pageKey) : null, [area, pageKey, regionDrafts, selectedRegionKey]);
+    const selectedRootDraft = useMemo(() => selectedRootRegionKey ? resolveRegionDraftKey(regionDrafts, area, selectedRootRegionKey, pageKey) : null, [area, pageKey, regionDrafts, selectedRootRegionKey]);
+    // The root Layout is found like every Layout below it.
+    const { selectedLayoutNode, selectedWidgetNode } = useMemo(() => {
+        const selectedRootLayouts = selectedRootDraft?.rootNode ? [selectedRootDraft.rootNode] : [];
+        return {
+            selectedLayoutNode: nodeKind === "layout" && nodeId != null ? findPhiBuilderLayoutNodeById(selectedRootLayouts, nodeId) : null,
+            selectedWidgetNode: nodeId != null ? findPhiBuilderWidgetNodeByIdInLayouts(selectedRootLayouts, nodeId) : null,
+        };
+    }, [nodeId, nodeKind, selectedRootDraft]);
     /*
      * Which plugin the selection is, asked in the order that can only answer about the selection itself.
      *
-     * The root node's type belongs to the root node. Reaching for it whenever a nested layout was not
-     * found in the draft answers with a DIFFERENT block: the Inspector then read its fields off the root
-     * -- a Content wrapper declares nothing but padding -- and the Settings panel, which hides itself when
-     * a layout declares no settings, hid for every layout on the page. The header kept the right name the
-     * whole time, because `PhiInspectorTitle` resolves the plugin from `nodeKey` instead.
-     *
-     * So the root's type is used only where the selection IS the root, and everything else falls back to
-     * `nodeKey`, which is what the title already matches on. A missing draft now costs the fields of the
-     * block that is selected, never the fields of another one.
+     * Only the selected node's own type answers. Reaching for another block's type whenever the
+     * selection was not found in the draft answers with a DIFFERENT block: the Inspector then read its
+     * fields off the root -- a Content wrapper declares nothing but padding -- and the Settings panel,
+     * which hides itself when a layout declares no settings, hid for every layout on the page. So a node
+     * not found falls back to `nodeKey`, which is what `PhiInspectorTitle` matches on as well.
      */
     const selectedStructureTypeKey = nodeKind === "widget"
         ? selectedWidgetNode?.widgetType ?? nodeKey
         : nodeKind === "layout"
-            ? selectedNestedLayoutNode?.widgetType
-                ?? (nodeId == null || nodeId === selectedRootNodeId ? selectedRootDraft?.rootNodeTypeKey : null)
-                ?? nodeKey
+            ? selectedLayoutNode?.widgetType ?? nodeKey
             : nodeKey;
     const selectedStructurePlugin = activeBuilderPlugins.find((plugin) => plugin.kind === nodeKind &&
         (plugin.typeKey === selectedStructureTypeKey ||
@@ -192,13 +131,15 @@ function usePhiBuilderInspectorSectionState(signalRoutes) {
             null)
         : null) ?? selectedLayoutAnchor;
     const selectedSignalRouteScope = selectedRootRegionKey && isPhiBuilderPageScopedRegion(selectedRootRegionKey) ? "page" : "area";
-    const selectedStructureDraft = resolveDraftFromLayoutNode(selectedNestedLayoutNode, selectedStructurePlugin?.kind !== "widget" ? selectedStructurePlugin : null) ??
-        resolveDraftFromRootNodeDraft(selectedRootDraft, selectedStructurePlugin?.kind !== "widget" ? selectedStructurePlugin : null);
-    const widgetReferenceOptions = collectWidgetReferenceOptionsFromDrafts(regionDrafts, area, pageKey);
+    const selectedStructureDraft = resolveDraftFromLayoutNode(selectedLayoutNode, selectedStructurePlugin?.kind !== "widget" ? selectedStructurePlugin : null);
+    const widgetReferenceOptions = useMemo(() => collectWidgetReferenceOptionsFromDrafts(regionDrafts, area, pageKey), [area, pageKey, regionDrafts]);
     const emitInspectorControllerAction = (value) => {
-        const routes = signalRoutes?.emits?.filter((route) => route.capabilityId === "change") ?? [];
-        if (routes.length === 0)
-            return;
+        const routes = (signalRoutes?.emits ?? [])
+            .filter((route) => route.capabilityId === "change" && route.receiver != null);
+        // An Inspector wired to nobody would take every edit and drop it; that is a broken preset, said here.
+        if (routes.length === 0) {
+            throw new Error("Builder Inspector has no `change` route with a receiver; its edits would reach nobody.");
+        }
         for (const route of routes) {
             if (route.receiver == null)
                 continue;
@@ -235,15 +176,15 @@ function usePhiBuilderInspectorSectionState(signalRoutes) {
         widgetReferenceOptions,
     };
 }
-export function PhiBuilderRegionInspectorSectionWidgetClient({ section, signalRoutes, geometryLabels, paddingLabels, backgroundLabels, borderLabels, colorPickerLabels, }) {
+export function PhiBuilderRegionInspectorSectionWidgetClient({ section, signalRoutes, visibilityLabels, geometryLabels, paddingLabels, backgroundLabels, borderLabels, surfaceLabels, colorPickerLabels, }) {
     const state = usePhiBuilderInspectorSectionState(signalRoutes);
-    return _jsx(PhiDeveloperBuilderRegionInspectorWidgetClient, { section: section, builderMode: state.builderMode, selectedStructureNodeKey: state.nodeKey, selectedStructureNodeKind: state.nodeKind, selectedRegionKey: state.selectedRegionKey, selectedRootRegionKey: state.selectedRootRegionKey, currentDraft: state.currentRegionDraft, onDraftChange: (patch) => state.emitInspectorControllerAction({ kind: "patchSelectedRegionDraft", patch }), geometryLabels: geometryLabels, backgroundLabels: backgroundLabels, borderLabels: borderLabels, colorPickerLabels: colorPickerLabels, paddingLabels: paddingLabels, renderMediaPicker: state.renderBackgroundMediaPicker });
+    return _jsx(PhiDeveloperBuilderRegionInspectorWidgetClient, { surfaceLabels: surfaceLabels, visibilityLabels: visibilityLabels, section: section, builderMode: state.builderMode, selectedStructureNodeKey: state.nodeKey, selectedStructureNodeKind: state.nodeKind, selectedRegionKey: state.selectedRegionKey, selectedRootRegionKey: state.selectedRootRegionKey, currentDraft: state.currentRegionDraft, onDraftChange: (patch) => state.emitInspectorControllerAction({ kind: "patchSelectedRegionDraft", patch }), geometryLabels: geometryLabels, backgroundLabels: backgroundLabels, borderLabels: borderLabels, colorPickerLabels: colorPickerLabels, paddingLabels: paddingLabels, renderMediaPicker: state.renderBackgroundMediaPicker });
 }
-export function PhiBuilderLayoutInspectorSectionWidgetClient({ section, signalRoutes, signalsLabels, paddingLabels, backgroundLabels, borderLabels, colorPickerLabels, iconPickerLabels, }) {
+export function PhiBuilderLayoutInspectorSectionWidgetClient({ section, signalRoutes, signalsLabels, paddingLabels, backgroundLabels, borderLabels, surfaceLabels, gridLabels, fieldLabels, colorPickerLabels, iconPickerLabels, }) {
     const state = usePhiBuilderInspectorSectionState(signalRoutes);
-    return _jsx(PhiDeveloperBuilderLayoutInspectorWidgetClient, { section: section, builderMode: state.builderMode, selectedStructureNodeKind: state.nodeKind, selectedStructureNodeTitle: state.selectedStructureNodeTitle, selectedStructurePlugin: state.selectedStructurePlugin?.kind !== "widget" ? state.selectedStructurePlugin : null, selectedStructureDefaultConfig: resolvePhiBuilderPluginDefaultConfig(state.selectedStructurePlugin) ?? null, currentDraft: state.selectedStructureDraft, currentShadow: state.selectedStructureDraft?.rootNodeShadow ?? null, signalRouteScope: state.selectedSignalRouteScope, selectedLayoutAnchor: state.selectedLayoutAnchor, onLayoutAnchorChange: (selectedLayoutAnchor) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutAnchor", selectedLayoutAnchor }), onPaddingChange: (padding) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutPadding", padding }), onBackgroundChange: (background) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutBackground", background }), onBorderChange: (border) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutBorder", border }), onShadowChange: (shadow) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutShadow", shadow }), onConfigChange: (key, value) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutConfig", key, value: value ?? undefined }), borderLabels: borderLabels, paddingLabels: paddingLabels, backgroundLabels: backgroundLabels, signalsLabels: signalsLabels, colorPickerLabels: colorPickerLabels, iconPickerLabels: iconPickerLabels, dataProviderDescriptors: state.activeDataProviderDescriptors, calendarAdapterDescriptors: state.activeCalendarAdapterDescriptors, videoProviderDescriptors: state.activeVideoProviderDescriptors, renderMediaPicker: state.renderBackgroundMediaPicker });
+    return _jsx(PhiDeveloperBuilderLayoutInspectorWidgetClient, { surfaceLabels: surfaceLabels, gridLabels: gridLabels, fieldLabels: fieldLabels, section: section, builderMode: state.builderMode, selectedStructureNodeKind: state.nodeKind, selectedStructureNodeTitle: state.selectedStructureNodeTitle, selectedStructurePlugin: state.selectedStructurePlugin?.kind !== "widget" ? state.selectedStructurePlugin : null, selectedStructureDefaultConfig: resolvePhiBuilderPluginDefaultConfig(state.selectedStructurePlugin) ?? null, currentDraft: state.selectedStructureDraft, signalRouteScope: state.selectedSignalRouteScope, selectedLayoutAnchor: state.selectedLayoutAnchor, onLayoutAnchorChange: (selectedLayoutAnchor) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutAnchor", selectedLayoutAnchor }), onPaddingChange: (padding) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutPadding", padding }), onSurfaceChange: (surface) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutSurface", surface }), onConfigPatch: (patch) => state.emitInspectorControllerAction({ kind: "patchSelectedLayoutConfig", patch }), onTranslateChange: (translate) => state.emitInspectorControllerAction({ kind: "setSelectedLayoutTranslate", translate }), borderLabels: borderLabels, paddingLabels: paddingLabels, backgroundLabels: backgroundLabels, signalsLabels: signalsLabels, colorPickerLabels: colorPickerLabels, iconPickerLabels: iconPickerLabels, dataProviderDescriptors: state.activeDataProviderDescriptors, calendarAdapterDescriptors: state.activeCalendarAdapterDescriptors, videoProviderDescriptors: state.activeVideoProviderDescriptors, renderMediaPicker: state.renderBackgroundMediaPicker });
 }
-export function PhiBuilderWidgetInspectorSectionWidgetClient({ section, signalRoutes, geometryLabels, signalsLabels, colorPickerLabels, iconPickerLabels, }) {
+export function PhiBuilderWidgetInspectorSectionWidgetClient({ section, signalRoutes, geometryLabels, surfaceLabels, backgroundLabels, borderLabels, signalsLabels, fieldLabels, colorPickerLabels, iconPickerLabels, }) {
     const state = usePhiBuilderInspectorSectionState(signalRoutes);
-    return _jsx(PhiDeveloperBuilderWidgetInspectorWidgetClient, { section: section, builderMode: state.builderMode, selectedStructureNodeKey: state.nodeKey, selectedStructureNodeKind: state.nodeKind, selectedStructureNodeTitle: state.selectedStructureNodeTitle, selectedStructureWidgetMeta: state.selectedStructurePlugin?.kind === "widget" ? state.selectedStructurePlugin : null, currentDraft: state.selectedWidgetNode, widgetReferenceOptions: state.widgetReferenceOptions, signalRouteScope: state.selectedSignalRouteScope, onConfigChange: (nextConfig) => state.emitInspectorControllerAction({ kind: "patchSelectedWidgetConfig", patch: nextConfig }), geometryLabels: geometryLabels, signalsLabels: signalsLabels, colorPickerLabels: colorPickerLabels, iconPickerLabels: iconPickerLabels, dataProviderDescriptors: state.activeDataProviderDescriptors, calendarAdapterDescriptors: state.activeCalendarAdapterDescriptors, videoProviderDescriptors: state.activeVideoProviderDescriptors, onGeometryChange: (geometry) => state.emitInspectorControllerAction({ kind: "patchSelectedWidgetGeometry", geometry }), onTranslateChange: (translate) => state.emitInspectorControllerAction({ kind: "setSelectedWidgetTranslate", translate }) });
+    return _jsx(PhiDeveloperBuilderWidgetInspectorWidgetClient, { surfaceLabels: surfaceLabels, fieldLabels: fieldLabels, backgroundLabels: backgroundLabels, borderLabels: borderLabels, renderMediaPicker: state.renderBackgroundMediaPicker, onSurfaceChange: (surface) => state.emitInspectorControllerAction({ kind: "patchSelectedWidgetSurface", surface }), section: section, builderMode: state.builderMode, selectedStructureNodeKey: state.nodeKey, selectedStructureNodeKind: state.nodeKind, selectedStructureNodeTitle: state.selectedStructureNodeTitle, selectedStructureWidgetMeta: state.selectedStructurePlugin?.kind === "widget" ? state.selectedStructurePlugin : null, currentDraft: state.selectedWidgetNode, widgetReferenceOptions: state.widgetReferenceOptions, signalRouteScope: state.selectedSignalRouteScope, onConfigChange: (nextConfig) => state.emitInspectorControllerAction({ kind: "patchSelectedWidgetConfig", patch: nextConfig }), geometryLabels: geometryLabels, signalsLabels: signalsLabels, colorPickerLabels: colorPickerLabels, iconPickerLabels: iconPickerLabels, dataProviderDescriptors: state.activeDataProviderDescriptors, calendarAdapterDescriptors: state.activeCalendarAdapterDescriptors, videoProviderDescriptors: state.activeVideoProviderDescriptors, onGeometryChange: (geometry) => state.emitInspectorControllerAction({ kind: "patchSelectedWidgetGeometry", geometry }), onTranslateChange: (translate) => state.emitInspectorControllerAction({ kind: "setSelectedWidgetTranslate", translate }) });
 }

package/plugins/runtime-modules/builder/clients/inspector-surface-labels.d.ts

@@ -0,0 +1,8 @@
+import type { PhiSurfaceControlLabels } from "../../../../components/controls/phi-surface-control";
+import type { PhiInspectorWidgetLabels } from "../../../../components/widgets/label-types/inspector";
+/** The words a Surface section needs: its own title, and the headings of its three parts. */
+export type PhiInspectorSurfaceLabels = {
+    section: string;
+    parts: PhiSurfaceControlLabels;
+};
+export declare function resolvePhiInspectorSurfaceLabels(labels: PhiInspectorWidgetLabels): PhiInspectorSurfaceLabels;

package/plugins/runtime-modules/builder/clients/inspector-surface-labels.js

@@ -0,0 +1,24 @@
+export function resolvePhiInspectorSurfaceLabels(labels) {
+    return {
+        section: labels.sections.surface,
+        parts: {
+            style: labels.surfaceStyle.title,
+            styles: {
+                none: labels.surfaceStyle.none,
+                card: labels.surfaceStyle.card,
+                wash: labels.surfaceStyle.wash,
+                custom: labels.surfaceStyle.custom,
+            },
+            background: labels.sections.background,
+            border: labels.sections.border,
+            shadow: labels.sections.shadow,
+            tone: labels.tone.title,
+            tones: {
+                inherit: labels.tone.inherit,
+                light: labels.tone.light,
+                dark: labels.tone.dark,
+                inverse: labels.tone.inverse,
+            },
+        },
+    };
+}

package/plugins/runtime-modules/builder/clients/inspector-title.js

@@ -4,7 +4,7 @@ import { useMemo } from "react";
 import { PhiTagControl } from "../../../../components/controls/phi-tag-control";
 import { getPhiRegionWidgetLabelEntry } from "../../../../components/widgets/label-types/region";
 import { usePhiBuilderModuleMetas } from "../plugin-meta-store";
-import { findPhiBuilderLayoutNodeById, findPhiBuilderWidgetNodeByIdInLayouts, findPhiBuilderWidgetNodeByIdInWidgets, } from "../node-finders";
+import { findPhiBuilderLayoutNodeById, findPhiBuilderWidgetNodeByIdInLayouts, } from "../node-finders";
 import { resolveRegionDraftKey } from "../developer-region-drafts";
 import { usePhiDeveloperBuilderStateValue, usePhiDeveloperRegionDrafts, } from "../developer-workspace-store";
 export function PhiBuilderInspectorTitleWidgetClient({ inspectorLabels, regionLabels, }) {
@@ -33,19 +33,18 @@ export function PhiBuilderInspectorTitleWidgetClient({ inspectorLabels, regionLa
         const rootDraft = selectedRootRegionKey
             ? resolveRegionDraftKey(regionDrafts, area, selectedRootRegionKey, pageKey)
             : null;
-        const nestedLayout = nodeKind === "layout" && rootDraft && nodeId != null
-            ? findPhiBuilderLayoutNodeById(rootDraft.rootNodeChildLayouts ?? [], nodeId)
+        const rootLayouts = rootDraft?.rootNode ? [rootDraft.rootNode] : [];
+        const layout = nodeKind === "layout" && nodeId != null
+            ? findPhiBuilderLayoutNodeById(rootLayouts, nodeId)
             : null;
-        const widget = nodeKind === "widget" && rootDraft && nodeId != null
-            ? findPhiBuilderWidgetNodeByIdInWidgets(rootDraft.rootNodeChildWidgets ?? [], nodeId) ??
-                findPhiBuilderWidgetNodeByIdInLayouts(rootDraft.rootNodeChildLayouts ?? [], nodeId)
+        const widget = nodeKind === "widget" && nodeId != null
+            ? findPhiBuilderWidgetNodeByIdInLayouts(rootLayouts, nodeId)
             : null;
         const fallback = nodeKind === "layout" ? inspectorLabels.layout : inspectorLabels.widget;
         return {
             kind: fallback,
             color: nodeKind === "layout" ? "green" : "orange",
-            name: plugin?.title ?? nestedLayout?.label ?? widget?.label ??
-                (nodeKind === "layout" ? rootDraft?.rootNodeTitle : null) ?? fallback,
+            name: plugin?.title ?? layout?.label ?? widget?.label ?? fallback,
             origin: plugin ? `${plugin.pluginKey}/${plugin.typeKey}` : nodeKey,
         };
     }, [area, inspectorLabels, nodeId, nodeKey, nodeKind, pageKey, plugins, regionDrafts, regionLabels, selectedRootRegionKey]);