@phis/ui 0.1.0 → 0.2.1

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

@@ -1,12 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import Image from "next/image";
 import { Flex } from "antd";
 import { buildPhiMediaAssetContentDeliveryUrl } from "../../constants/media";
+import { PhiIcon } from "../shell/phi-icon";
 const PHI_FONT_SIZE_XL = "1.25rem";
 const PHI_LINE_HEIGHT_LG = 1.6;
 /** How tall a Logo is drawn. Its width follows the artwork, so a wordmark reads as well as a signet. */
-const PHI_BRAND_LOGO_HEIGHT = 50;
+const PHI_BRAND_LOGO_HEIGHT = 32;
 /**
  * The address a mode's Logo is drawn from, or none.
  *
@@ -28,7 +28,19 @@ export function resolvePhiBrandLogoUrl(brand, mode) {
 function hasWordmarkParts(parts) {
     return Array.isArray(parts) && parts.some((part) => typeof part?.text === "string" && part.text.trim());
 }
+/**
+ * A Brand that has said it draws no name.
+ *
+ * Asked before the parts and before the fallback, because it outranks both: the fallback exists for a
+ * Site that has not set a name yet, and this is a Site saying its name is not set in type at all.
+ */
+function wordmarkIsSwitchedOff(wordmark) {
+    return wordmark?.shows === "none";
+}
 function renderWordmark(wordmark, fallbackTitle, fallbackStyle) {
+    if (wordmarkIsSwitchedOff(wordmark)) {
+        return null;
+    }
     const wordmarkStyle = {
         ...(fallbackStyle ?? {}),
         ...(wordmark?.fontFamily ? { fontFamily: wordmark.fontFamily } : {}),
@@ -50,16 +62,43 @@ function renderWordmark(wordmark, fallbackTitle, fallbackStyle) {
                 ...(part.fontWeight ? { fontWeight: part.fontWeight } : {}),
             }, children: part.text }, `${part.text}-${index}`))) }));
 }
+/**
+ * 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 function PhiBrandLineControl({ line, fallbackIcon, fontFamily, fontSize, }) {
+    const label = line?.label?.trim();
+    if (!label) {
+        return null;
+    }
+    const icon = line?.icon?.trim() || fallbackIcon;
+    return (_jsxs(Flex, { align: "center", gap: 8, wrap: false, style: {
+            color: "inherit",
+            minWidth: 0,
+            fontFamily,
+            fontSize,
+            // The leading comes with the size, and only with it: without one the line reads as its surroundings.
+            lineHeight: fontSize == null ? undefined : PHI_LINE_HEIGHT_LG,
+        }, children: [icon ? _jsx(PhiIcon, { name: icon, size: "inherit" }) : null, _jsx("span", { style: { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }, children: label })] }));
+}
 /**
  * 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 function phiBrandControlIsEmpty({ brand, fallbackTitle, fallbackEyebrow, showLogo = true, mode, }) {
-    const hasLogo = showLogo !== false && Boolean(resolvePhiBrandLogoUrl(brand, mode));
-    const hasWordmark = hasWordmarkParts(brand?.wordmark?.parts) || Boolean(fallbackTitle);
-    const hasEyebrow = Boolean(brand?.eyebrow ?? fallbackEyebrow);
+export function phiBrandControlIsEmpty({ brand, fallbackTitle, shows = "lockup", mode, }) {
+    const drawsName = shows !== "logo" && !wordmarkIsSwitchedOff(brand?.wordmark);
+    const hasLogo = shows !== "wordmark" && Boolean(resolvePhiBrandLogoUrl(brand, mode));
+    const hasWordmark = drawsName
+        && (hasWordmarkParts(brand?.wordmark?.parts) || Boolean(fallbackTitle));
+    const hasEyebrow = drawsName && Boolean(brand?.eyebrow);
     return !hasLogo && !hasWordmark && !hasEyebrow;
 }
 /**
@@ -70,29 +109,46 @@ export function phiBrandControlIsEmpty({ brand, fallbackTitle, fallbackEyebrow,
  * 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 function PhiBrandControl({ brand, fallbackTitle, fallbackEyebrow, showLogo = true, logoYOffset = 0, mode, }) {
-    const eyebrow = brand?.eyebrow ?? fallbackEyebrow ?? null;
-    const wordmarkNode = renderWordmark(brand?.wordmark, fallbackTitle, {
-        fontSize: PHI_FONT_SIZE_XL,
-        lineHeight: PHI_LINE_HEIGHT_LG,
-    });
+export function PhiBrandControl({ brand, fallbackTitle, shows = "lockup", mode, }) {
+    /*
+     * The Eyebrow travels with the Wordmark, so it goes where the Wordmark does -- switched off by the
+     * Brand as much as left out by the placement. It is the line above the name; above a bare Logo it
+     * would sit over nothing.
+     */
+    const eyebrow = shows === "logo" || wordmarkIsSwitchedOff(brand?.wordmark)
+        ? null
+        : brand?.eyebrow ?? null;
+    const wordmarkNode = shows === "logo"
+        ? null
+        : renderWordmark(brand?.wordmark, fallbackTitle, {
+            fontSize: PHI_FONT_SIZE_XL,
+            lineHeight: PHI_LINE_HEIGHT_LG,
+        });
+    /*
+     * The Logo's own correction, read from the Brand and not from the placement.
+     *
+     * What it corrects is whitespace inside the artwork -- how the picture sits against type -- so it is
+     * true of the Logo wherever it is drawn, and was set per Widget instance until now: the same picture
+     * was aligned by hand in the header and again in the footer, and the two drifted.
+     */
+    const logoYOffset = brand?.logoYOffset ?? 0;
     /*
      * No Logo means no Logo. It used to mean the Phi logo, which was a placeholder from before a Site
      * could set one of its own -- every Site that had not picked a picture wore ours, and there was no
      * way to say "wordmark only" at all. The Wordmark carries the Brand where nothing is picked.
      */
-    const logoUrl = resolvePhiBrandLogoUrl(brand, mode);
+    const logoUrl = shows === "wordmark" ? null : resolvePhiBrandLogoUrl(brand, mode);
     const logoAlt = brand?.logoAlt?.trim() || "Brand logo";
     if (!logoUrl && !wordmarkNode && !eyebrow) {
         return null;
     }
-    return (_jsxs(Flex, { align: "center", justify: "flex-start", gap: 12, wrap: false, style: { color: "inherit", width: "100%", height: "100%", fontSize: PHI_FONT_SIZE_XL }, children: [showLogo && logoUrl ? (_jsx("span", { style: {
+    return (_jsxs(Flex, { align: "center", justify: "flex-start", gap: 12, wrap: false, style: { color: "inherit", width: "100%", height: "100%", fontSize: PHI_FONT_SIZE_XL }, children: [logoUrl ? (_jsx("span", { style: {
                     display: "flex",
                     alignItems: "center",
                     justifyContent: "center",
                     height: "100%",
                     flexShrink: 0,
-                }, children: _jsx(Image, { src: logoUrl, alt: logoAlt, width: PHI_BRAND_LOGO_HEIGHT, height: PHI_BRAND_LOGO_HEIGHT, unoptimized: true, style: {
+                }, children: _jsx("img", { src: logoUrl, alt: logoAlt, height: PHI_BRAND_LOGO_HEIGHT, decoding: "async", style: {
                         width: "auto",
                         height: PHI_BRAND_LOGO_HEIGHT,
                         objectFit: "contain",

package/components/controls/phi-builder-insert-picker-control-labels.d.ts

@@ -6,6 +6,8 @@ export type PhiBuilderInsertPickerControlLabels = {
     searchLayouts: string;
     searchWidgets: string;
     filterPackages: string;
+    /** The entry that stands for no package filter at all. */
+    allPackages: string;
     filterCategories: string;
     noCompatibleItems: string;
 };

package/components/controls/phi-builder-insert-picker-control-labels.js

@@ -6,6 +6,7 @@ export const PHI_BUILDER_INSERT_PICKER_CONTROL_DEFAULT_LABELS = {
     searchLayouts: "Search layouts",
     searchWidgets: "Search widgets",
     filterPackages: "Filter packages",
+    allPackages: "All packages",
     filterCategories: "Filter categories",
     noCompatibleItems: "No compatible items found.",
 };

package/components/controls/phi-builder-insert-picker-control.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
-import { Flex, Input, Segmented, Select, Space, Tag, Tooltip, Typography, theme as antdTheme } from "antd";
+import { Flex, Input, Segmented, Select, Tag, Tooltip, Typography, theme as antdTheme } from "antd";
 import { PhiIcon } from "../shell/phi-icon";
+import { PhiFlexControl } from "./phi-flex-control";
 import { PhiPopoverControl } from "./phi-popover-control";
 import { usePhiImmediatePicker } from "./use-phi-immediate-picker";
 import { PHI_BUILDER_INSERT_PICKER_CONTROL_DEFAULT_LABELS, } from "./phi-builder-insert-picker-control-labels";
@@ -44,6 +45,59 @@ function resolveItemCategoryTagColor(category) {
         default: return "blue";
     }
 }
+/**
+ * Two items side by side, for Layouts and for Widgets alike.
+ *
+ * An entry is an icon, a name and the category under it -- narrow enough that one per row left half
+ * the popover empty and pushed a catalogue of seventy Widgets into a long scroll. Two columns halve
+ * that scroll without widening anything, which is the whole reason the entry gave up the rest.
+ */
+const PHI_INSERT_PICKER_COLUMNS = 2;
+/**
+ * The package filter's standing answer.
+ *
+ * A word and not an empty string, because a Select tells an empty value apart from no value only by
+ * accident: the entry has to be selectable, and what it selects is "do not filter".
+ */
+const PHI_INSERT_PICKER_ALL_PACKAGES = "__all__";
+/**
+ * The step of the house sequence this popover stands on -- 144, 233, 377, 610, 987.
+ *
+ * 377 is what two entries need once an entry is an icon, a name and the category under it. What an
+ * entry used to print beside the name -- the package it came from, its tags -- is in the hover text
+ * instead: at this width they would each have taken more room than the name they stood next to, and a
+ * name that is cut off is worth less than a package line that has to be asked for.
+ */
+const PHI_INSERT_PICKER_MAX_WIDTH = 377;
+/**
+ * How tall the list stands, on the same sequence as the width -- 144, 233, 377, 610, 987.
+ *
+ * A height and not a ceiling: the list is the one part of the popover that changes size as somebody
+ * types or picks a category, and a popover that grows and shrinks under the cursor moves the entry
+ * that was about to be clicked. Fixed, the filters change what is in the box and never the box.
+ *
+ * `controlHeight * 12` was 408, which is not a step of anything: near enough to 377 to look like it
+ * and far enough to sit wrong beside a popover that is 377 wide. The box is now square, which is the
+ * one proportion that needs no justification.
+ */
+const PHI_INSERT_PICKER_LIST_HEIGHT = 377;
+/**
+ * What an entry no longer prints, gathered for the hover text.
+ *
+ * Description, package and tags all answer "which one is this?", which is a question asked of one
+ * entry at a time -- not of the whole list at once, which is what printing them in every row amounts
+ * to. The category is the exception and stays in the row, under the name: it is the one word that
+ * sorts a catalogue of seventy into groups, so it is read down the list rather than per entry -- and
+ * a line of its own costs the name nothing, where beside the name it would have taken most of it.
+ */
+function renderItemDetails(item) {
+    const packageName = resolveItemPackageName(item);
+    const tags = item.tags ?? [];
+    if (!item.description && !packageName && tags.length === 0) {
+        return undefined;
+    }
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: 4, align: "flex-start", children: [_jsx(Typography.Text, { strong: true, style: { color: "inherit" }, children: item.title }), item.description ? _jsx(Typography.Text, { style: { color: "inherit" }, children: item.description }) : null, packageName ? _jsx(Typography.Text, { style: { color: "inherit" }, children: packageName }) : null, tags.length > 0 ? (_jsx(PhiFlexControl, { align: "center", gap: 4, wrap: true, children: tags.map((tag) => _jsx(Tag, { color: "blue", style: { marginInlineEnd: 0 }, children: tag }, tag)) })) : null] }));
+}
 const WIDGET_CATEGORY_ORDER = [
     "content",
     "navigation",
@@ -81,10 +135,9 @@ export function PhiBuilderInsertPickerControl({ open, trigger, items, section, p
         },
     });
     const [search, setSearch] = useState("");
-    const popoverWidth = Math.min(token.controlHeight * 26, 420);
+    const popoverWidth = Math.min(token.controlHeight * 38, PHI_INSERT_PICKER_MAX_WIDTH);
     const popoverMaxWidth = `calc(100vw - ${token.paddingLG * 2}px)`;
     const popoverHeight = `min(${token.controlHeight * 18}px, calc(100vh - ${token.paddingLG * 2}px))`;
-    const listMaxHeight = token.controlHeight * 12;
     const itemIconFrameSize = token.controlHeight;
     const itemIconSize = token.fontSizeHeading3;
     const normalizedSearch = normalizeSearchText(search);
@@ -108,6 +161,12 @@ export function PhiBuilderInsertPickerControl({ open, trigger, items, section, p
             return false;
         return !normalizedSearch || buildItemSearchText(item).includes(normalizedSearch);
     });
+    /*
+     * The bottom rule belongs to the last row, not to the last item: in two columns the item before the
+     * last one sits beside it rather than above it, and a rule under it would hang in the middle.
+     */
+    const lastRowStartIndex = Math.floor(Math.max(visibleItems.length - 1, 0) / PHI_INSERT_PICKER_COLUMNS)
+        * PHI_INSERT_PICKER_COLUMNS;
     const title = section === "widget" ? labels.pickWidget : labels.pickLayout;
     const placeholder = section === "widget" ? labels.searchWidgets : labels.searchLayouts;
     const selectItem = (item) => {
@@ -121,7 +180,10 @@ export function PhiBuilderInsertPickerControl({ open, trigger, items, section, p
             display: "flex",
             flexDirection: "column",
             overflow: "hidden",
-        }, onClick: (event) => event.stopPropagation(), onMouseDown: (event) => event.stopPropagation(), onPointerDown: (event) => event.stopPropagation(), onKeyDown: (event) => event.stopPropagation(), children: _jsxs(Flex, { vertical: true, gap: token.paddingSM, style: { width: "100%", minHeight: 0, overflow: "hidden" }, children: [_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingSM, wrap: true, children: [_jsx(Typography.Text, { strong: true, style: { fontSize: token.fontSize }, children: title }), _jsx(Segmented, { value: section, onChange: (nextSection) => {
+        }, onClick: (event) => event.stopPropagation(), onMouseDown: (event) => event.stopPropagation(), onPointerDown: (event) => event.stopPropagation(), onKeyDown: (event) => event.stopPropagation(), children: _jsxs(Flex, { vertical: true, gap: token.paddingSM, style: { width: "100%", minHeight: 0, overflow: "hidden" }, children: [_jsxs(Flex, { align: "center", justify: "space-between", gap: token.paddingSM, wrap: true, children: [_jsx(Typography.Text, { strong: true, style: { fontSize: token.fontSize }, children: title }), packageOptions.length > 1 ? (_jsx(Select, { size: "small", variant: "borderless", showSearch: false, value: packageFilters[0] ?? PHI_INSERT_PICKER_ALL_PACKAGES, onChange: (nextPackage) => onPackageFiltersChange(nextPackage === PHI_INSERT_PICKER_ALL_PACKAGES ? [] : [nextPackage]), options: [
+                                { value: PHI_INSERT_PICKER_ALL_PACKAGES, label: labels.allPackages },
+                                ...packageOptions.map((packageName) => ({ value: packageName, label: packageName })),
+                            ], "aria-label": labels.filterPackages, style: { flex: "1 1 0", minWidth: 0 } })) : null, section === "widget" && categoryOptions.length > 1 ? (_jsx(Select, { mode: "multiple", size: "small", variant: "borderless", allowClear: true, showSearch: false, value: [...widgetCategoryFilters], onChange: onWidgetCategoryFiltersChange, options: categoryOptions.map((category) => ({ value: category, label: category })), placeholder: labels.filterCategories, "aria-label": labels.filterCategories, maxTagCount: "responsive", style: { flex: "1 1 0", minWidth: 0 } })) : null, _jsx(Segmented, { value: section, onChange: (nextSection) => {
                                 if (nextSection === "layout" && !allowLayoutSection) {
                                     onSectionChange("widget");
                                     return;
@@ -135,43 +197,43 @@ export function PhiBuilderInsertPickerControl({ open, trigger, items, section, p
                         borderRadius: 0,
                         paddingInline: 0,
                         boxShadow: "none",
-                    } }), _jsx(Select, { mode: "multiple", allowClear: true, showSearch: false, value: [...packageFilters], onChange: onPackageFiltersChange, options: packageOptions.map((packageName) => ({ value: packageName, label: packageName })), placeholder: labels.filterPackages, maxTagCount: "responsive", style: { width: "100%" } }), section === "widget" ? (_jsx(Select, { mode: "multiple", allowClear: true, showSearch: false, value: [...widgetCategoryFilters], onChange: onWidgetCategoryFiltersChange, options: categoryOptions.map((category) => ({ value: category, label: category })), placeholder: labels.filterCategories, maxTagCount: "responsive", style: { width: "100%" } })) : null, _jsx("div", { style: {
+                    } }), _jsx("div", { style: {
                         border: `1px solid ${token.colorBorderSecondary}`,
                         borderRadius: 0,
                         background: token.colorBgElevated,
                         padding: token.paddingSM,
-                        flex: "1 1 auto",
-                        minHeight: 0,
-                        maxHeight: listMaxHeight,
+                        flex: "0 1 auto",
+                        height: PHI_INSERT_PICKER_LIST_HEIGHT,
+                        maxHeight: "100%",
                         overflowY: "auto",
                         overflowX: "hidden",
-                    }, children: visibleItems.length > 0 ? (_jsx("div", { style: {
-                            display: "grid",
-                            gridTemplateColumns: section === "widget" ? "minmax(0, 1fr)" : "repeat(2, minmax(0, 1fr))",
-                            gap: token.paddingMD,
-                            width: "100%",
-                        }, children: _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingXS, width: "100%" }, children: [_jsx(Typography.Text, { type: "secondary", children: section === "widget" ? labels.widgets : labels.layouts }), _jsx(Space, { orientation: "vertical", size: 0, style: { width: "100%" }, children: visibleItems.map((item, index) => {
-                                        const isLast = index === visibleItems.length - 1;
-                                        const isActive = picker.value?.key === item.key;
-                                        return (_jsx("div", { role: "button", tabIndex: 0, style: {
-                                                cursor: "pointer",
-                                                paddingInline: 0,
-                                                paddingBlock: token.paddingSM,
-                                                borderBottom: isLast ? "none" : `1px solid ${token.colorBorderSecondary}`,
-                                                borderRadius: 0,
-                                                background: isActive ? token.colorFillQuaternary : "transparent",
-                                                outline: isActive ? `1px solid ${token.colorPrimary}` : "none",
-                                                outlineOffset: -1,
-                                            }, onClick: () => selectItem(item), onKeyDown: (event) => {
-                                                if (event.key !== "Enter" && event.key !== " ")
-                                                    return;
-                                                event.preventDefault();
-                                                selectItem(item);
-                                            }, children: _jsxs("div", { style: {
+                    }, children: visibleItems.length > 0 ? (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingXS, width: "100%" }, children: [_jsx(Typography.Text, { type: "secondary", children: section === "widget" ? labels.widgets : labels.layouts }), _jsx("div", { style: {
+                                    display: "grid",
+                                    gridTemplateColumns: `repeat(${PHI_INSERT_PICKER_COLUMNS}, minmax(0, 1fr))`,
+                                    columnGap: token.paddingSM,
+                                    width: "100%",
+                                }, children: visibleItems.map((item, index) => {
+                                    const isLast = index >= lastRowStartIndex;
+                                    const isActive = picker.value?.key === item.key;
+                                    return (_jsx("div", { role: "button", tabIndex: 0, style: {
+                                            cursor: "pointer",
+                                            paddingInline: 0,
+                                            paddingBlock: token.paddingSM,
+                                            borderBottom: isLast ? "none" : `1px solid ${token.colorBorderSecondary}`,
+                                            borderRadius: 0,
+                                            background: isActive ? token.colorFillQuaternary : "transparent",
+                                            outline: isActive ? `1px solid ${token.colorPrimary}` : "none",
+                                            outlineOffset: -1,
+                                        }, onClick: () => selectItem(item), onKeyDown: (event) => {
+                                            if (event.key !== "Enter" && event.key !== " ")
+                                                return;
+                                            event.preventDefault();
+                                            selectItem(item);
+                                        }, children: _jsx(Tooltip, { title: renderItemDetails(item), placement: "top", children: _jsxs("div", { style: {
                                                     display: "grid",
-                                                    gridTemplateColumns: `${itemIconFrameSize}px minmax(0, 1fr) auto`,
+                                                    gridTemplateColumns: `${itemIconFrameSize}px minmax(0, 1fr)`,
                                                     alignItems: "center",
-                                                    gap: token.paddingSM,
+                                                    gap: token.paddingXS,
                                                     width: "100%",
                                                 }, children: [_jsx("span", { style: {
                                                             width: itemIconFrameSize,
@@ -180,8 +242,8 @@ export function PhiBuilderInsertPickerControl({ open, trigger, items, section, p
                                                             display: "inline-flex",
                                                             alignItems: "center",
                                                             justifyContent: "center",
-                                                        }, children: _jsx(Tooltip, { title: item.description ?? undefined, placement: "top", children: _jsx(PhiIcon, { name: resolveItemIcon(item), size: itemIconSize }) }) }), _jsxs(Space, { orientation: "vertical", size: 0, style: { minWidth: 0 }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, children: item.title }), resolveItemPackageName(item) ? (_jsx(Typography.Text, { type: "secondary", children: resolveItemPackageName(item) })) : null] }), _jsxs(Space, { orientation: "vertical", size: 2, style: { alignItems: "flex-end" }, children: [item.kind === "widget" && item.category ? (_jsx(Tag, { color: resolveItemCategoryTagColor(item.category), style: { marginInlineEnd: 0 }, children: item.category })) : null, (item.tags ?? []).length > 0 ? (_jsx(Space, { size: 4, wrap: true, style: { justifyContent: "flex-end" }, children: (item.tags ?? []).map((tag) => _jsx(Tag, { color: "blue", children: tag }, tag)) })) : null] })] }) }, item.key));
-                                    }) })] }) })) : (_jsx(Typography.Text, { type: "secondary", children: labels.noCompatibleItems })) })] }) }));
+                                                        }, children: _jsx(PhiIcon, { name: resolveItemIcon(item), size: itemIconSize }) }), _jsxs(PhiFlexControl, { vertical: true, gap: 2, align: "flex-start", style: { minWidth: 0 }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, style: { minWidth: 0 }, children: item.title }), item.kind === "widget" && item.category ? (_jsx(Tag, { color: resolveItemCategoryTagColor(item.category), style: { marginInlineEnd: 0, maxWidth: "100%" }, children: item.category })) : null] })] }) }) }, item.key));
+                                }) })] })) : (_jsx(Typography.Text, { type: "secondary", children: labels.noCompatibleItems })) })] }) }));
     return (_jsx(PhiPopoverControl, { open: picker.open, trigger: "click", placement: placement, arrow: "point-at-center", destroyOnHidden: true, content: content, popupContentStyle: { overflow: "hidden" }, onOpenChange: (nextOpen) => {
             if (!nextOpen)
                 setSearch("");

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

@@ -1,4 +1,4 @@
-import type { ReactNode, Ref } from "react";
+import { type ReactNode, type Ref } from "react";
 import type { ButtonProps } from "antd";
 import type { PhiControlSize } from "../../types/control";
 import type { PhiButtonType } from "./phi-button-types";
@@ -29,12 +29,29 @@ export type PhiButtonControlProps = {
      * that mistake the easy one.
      */
     newTab?: boolean;
+    /**
+     * Whether the destination is outside this Site, stated rather than guessed.
+     *
+     * Absent leaves the answer to the same string test every other link falls back to. A caller that
+     * knows says so, and a caller that stores a structured target always knows: its target carries the
+     * kind, and reading it off a regex would put the decision back in a place that cannot see the
+     * difference between a Page and an address that merely starts the same way.
+     */
+    external?: boolean;
     tooltip?: ReactNode;
     icon?: ReactNode;
     type?: PhiButtonType;
     /** A round button is what an icon on its own wants, over a picture or in a toolbar. */
     shape?: ButtonProps["shape"];
     danger?: boolean;
+    /**
+     * Draws the button transparent with a coloured outline, for a surface the Theme's own fills fight.
+     *
+     * A hero over an image, a coloured band: there a filled button states a second background nobody
+     * asked for. This is Ant Design's own flag rather than a `PhiButtonType` of its own, because it is
+     * not a kind of button -- it is any kind of button, drawn for a background it does not own.
+     */
+    ghost?: boolean;
     disabled?: boolean;
     loading?: boolean;
     htmlType?: ButtonProps["htmlType"];
@@ -56,4 +73,4 @@ export type PhiButtonControlProps = {
     ref?: Ref<HTMLButtonElement | HTMLAnchorElement>;
     onClick?: () => void;
 };
-export declare function PhiButtonControl({ label, ariaLabel, href, newTab, tooltip, icon, type, shape, danger, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }: PhiButtonControlProps): import("react").JSX.Element;
+export declare function PhiButtonControl({ label, ariaLabel, href, newTab, external, tooltip, icon, type, shape, danger, ghost, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }: PhiButtonControlProps): import("react").JSX.Element;

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

@@ -1,19 +1,50 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import Link from "next/link";
-import { Badge, Button, Tooltip } from "antd";
-export function PhiButtonControl({ label, ariaLabel, href, newTab, tooltip, icon, type = "default", shape, danger, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }) {
+import { lazy, Suspense } from "react";
+import { Button } from "antd";
+import { PhiLink } from "../navigation/phi-link";
+import { PhiHoverText } from "./phi-hover-text";
+/*
+ * Ant Design's Badge, loaded where a Button actually carries a count. Most Buttons carry none, and the
+ * Landing's carry none at all, so a static import put the Badge and its scroll-number motion on every page
+ * that draws a Button.
+ */
+const PhiLazyBadge = lazy(() => import("antd/es/badge"));
+export function PhiButtonControl({ label, ariaLabel, href, newTab, external, tooltip, icon, type = "default", shape, danger, ghost, disabled, loading, htmlType, block, size, style, badge, className, ref, onClick, }) {
     const visibleTooltip = typeof label === "string" && typeof tooltip === "string" && label === tooltip
         ? null
         : tooltip;
-    const button = (_jsx(Button, { ref: ref, className: className, "aria-label": ariaLabel, type: type, shape: shape, danger: danger, disabled: disabled || (!onClick && !href && htmlType !== "submit"), loading: loading, htmlType: htmlType, block: block, size: size, style: style, icon: icon, onClick: onClick, children: label }));
+    const inert = disabled || (!onClick && !href && htmlType !== "submit");
+    const button = (_jsx(Button, { ref: ref, className: className, "aria-label": ariaLabel, type: type, shape: shape, danger: danger, ghost: ghost, disabled: inert, loading: loading, htmlType: htmlType, block: block, size: size, style: style, icon: icon, onClick: onClick, children: label }));
     /*
+     * Through `PhiLink`, which is where this house decides between a client navigation and a plain
+     * anchor -- and where `target="_blank"` and `rel` are one decision rather than two props that can
+     * disagree. This control used to reach for `next/link` itself, so an external address went through
+     * the client router and never received the `rel` that a new tab needs.
+     *
      * Never prefetched. A button-shaped link is a deliberate action rather than somewhere the visitor is
      * already heading, so speculating on it buys nothing -- and on a refusal page, where this is what the
      * home link is made of, it buys a request for the Area root that the visitor never asked for. An Area
      * root that forwards turns that into two.
+     *
+     * The colour is the Button's. A link states one, and here the Button beneath it already has.
      */
-    const linked = href && !disabled ? (_jsx(Link, { href: href, prefetch: false, target: newTab ? "_blank" : undefined, rel: newTab ? "noreferrer" : undefined, children: button })) : button;
-    const badged = badge?.enabled ? (_jsx(Badge, { color: badge.color, count: badge.value ?? 0, overflowCount: badge.overflowCount, showZero: badge.showZero, size: "small", children: linked })) : linked;
-    return visibleTooltip ? _jsx(Tooltip, { title: visibleTooltip, children: badged }) : badged;
+    const linked = href && !disabled ? (_jsx(PhiLink, { href: href, ...(external === undefined ? {} : { external }), newTab: newTab, prefetch: false, style: { display: "inline-flex", color: "inherit" }, children: button })) : button;
+    /*
+     * Rendered on the Server it is complete, and hydration waits for the chunk. Mounted in the browser before
+     * the chunk is there, the Button stands without its count until it arrives.
+     */
+    const badged = badge?.enabled ? (_jsx(Suspense, { fallback: linked, children: _jsx(PhiLazyBadge, { color: badge.color, count: badge.value ?? 0, overflowCount: badge.overflowCount, showZero: badge.showZero, size: "small", children: linked }) })) : linked;
+    if (!visibleTooltip)
+        return badged;
+    /*
+     * A disabled button emits no pointer events, so the tooltip the primitive hangs on it never opens --
+     * and a disabled button is exactly when the hover text matters most, because it is the only place the
+     * reason it is off can be read. The wrapper is what catches the pointer instead, and it exists only
+     * for that: an enabled button keeps the plain shape it always had.
+     */
+    const target = inert
+        ? _jsx("span", { style: { display: "inline-flex", cursor: "not-allowed" }, children: badged })
+        : badged;
+    return _jsx(PhiHoverText, { title: visibleTooltip, children: target });
 }

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

@@ -0,0 +1,61 @@
+import type { CSSProperties, ReactNode } from "react";
+/**
+ * A bordered box, with an optional heading bar above what is in it.
+ *
+ * **The body padding is the Theme's, not Ant Design's.** The primitive hard-codes 12 pixels for a small
+ * Card and reaches for `paddingLG` otherwise, and neither lands on the house scale: `paddingSM` is 13,
+ * and the ordinary padding a box gets is `padding`, where `paddingLG` on a Fibonacci scale is 55 and
+ * makes an ordinary section look like a feature. Four of the five small Cards in the tree had noticed the
+ * first half and written the same one-line override by hand; the fifth had not, and it was the Theme
+ * preview -- the one box whose entire job is to show what a Theme looks like was the one drawn off the
+ * Theme's own scale. Nobody decided any of that, and nobody should have to notice it again.
+ *
+ * **The corner and the colours arrive by themselves, and no caller passes them.** The corner is the Theme's
+ * surface step, `--phi-surface-radius` (THEME.md "Control shape"), so a Site set to `square` draws square
+ * corners here without this file or its callers knowing that shapes exist; the ground, the frame, the
+ * heading and the lift under the pointer are the Theme's tokens, read as the variables Ant Design
+ * publishes for them (`styles/controls.css`, "Card"). A box that names any of them by hand is a box that
+ * stops following the Theme the moment somebody changes it -- which is what every hand-built panel this
+ * control replaced did. The only decision left here is the inset, and that is the one below.
+ *
+ * **Not Ant Design's `Card`.** It imports the Tabs, for a tab list this house never offers, and every page
+ * with a card -- a sign-in form on a Landing among them -- shipped the Tabs code with it. The box is a frame,
+ * a heading bar and a body; drawing those is cheaper than carrying a component that brings what nobody
+ * asked for.
+ *
+ * `toolbar` sits where Ant Design put its `extra`, under the name this house already uses for it in
+ * `PhiCollectionHeaderControl`. A toolbar without a `title` still draws the heading bar, as the primitive
+ * this replaced did.
+ *
+ * **A card is a box, not a layout.** Anything that arranges what is inside it belongs to the caller's own
+ * element, which is why there is no body style: a Widget that wants its parts on a grid puts the grid in
+ * a `div` of its own rather than reaching into the Card's body through the primitive.
+ *
+ * `padding` is the exception, and it is not one of those: the inset of a box is the box's own business,
+ * which is why this control already decides it. A caller that needs a different one says so here. The
+ * alternative was a `div` wrapped around the Card to pad it from outside, which is a box around a box and
+ * pads the wrong side of the frame -- if a Card needs a wrapper to be spaced, the prop was missing.
+ */
+export type PhiCardControlProps = {
+    /** A heading in a bar of its own above the body, with a rule under it. */
+    title?: ReactNode;
+    /** What belongs to the heading rather than to the body -- an action, usually. */
+    toolbar?: ReactNode;
+    /** An opening image, drawn across the full width above the body. */
+    cover?: ReactNode;
+    /** `small` is the size of chrome -- an inspector panel, a preview frame -- against a card on a page. */
+    size?: "small" | "medium";
+    /** The box lifts under the pointer, which is how a card says that the whole of it is a link. */
+    hoverable?: boolean;
+    /**
+     * The body's own inset, where the Theme's answer is not the right one.
+     *
+     * Absent is the Theme's -- `padding` at the ordinary size and `paddingSM` for chrome -- and that stays
+     * the answer to "nothing was said" rather than becoming a ceiling. A Widget whose configuration carries
+     * a padding passes it straight through; nothing has to know which of the two it got.
+     */
+    padding?: number | string;
+    style?: CSSProperties;
+    children?: ReactNode;
+};
+export declare function PhiCardControl({ title, toolbar, cover, size, hoverable, padding, style, children, }: PhiCardControlProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePhiConfig } from "../root/phi-config-provider";
+export function PhiCardControl({ title, toolbar, cover, size = "medium", hoverable, padding, style, children, }) {
+    const { token } = usePhiConfig();
+    const className = [
+        "phi-card-control",
+        size === "small" ? "phi-card-control--small" : null,
+        hoverable ? "phi-card-control--hoverable" : null,
+    ].filter(Boolean).join(" ");
+    return (_jsxs("div", { className: className, style: style, children: [title != null || toolbar != null ? (_jsxs("div", { className: "phi-card-control__head", children: [title != null ? _jsx("div", { className: "phi-card-control__title", children: title }) : null, toolbar != null ? _jsx("div", { className: "phi-card-control__toolbar", children: toolbar }) : null] })) : null, cover != null ? _jsx("div", { className: "phi-card-control__cover", children: cover }) : null, _jsx("div", { className: "phi-card-control__body", style: { padding: padding ?? (size === "small" ? token.paddingSM : token.padding) }, children: children })] }));
+}

package/components/controls/phi-checkbox-group-control.js

@@ -1,10 +1,7 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Checkbox, Flex, Tooltip } from "antd";
-import { PhiIcon } from "../shell/phi-icon";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Checkbox, Flex } from "antd";
+import { PhiControlOptionContent } from "./phi-control-option-content";
 export function PhiCheckboxGroupControl({ value, options, disabled, readOnly, vertical, onChange, }) {
-    return (_jsx(Checkbox.Group, { value: [...(value ?? [])], disabled: disabled || readOnly || !onChange, onChange: (nextValue) => onChange?.(nextValue), style: { width: "100%" }, children: _jsx(Flex, { vertical: vertical, gap: "small", wrap: vertical ? false : "wrap", children: options.map((option) => {
-                const content = (_jsxs("span", { style: { display: "inline-flex", alignItems: "center", gap: "var(--ant-padding-xxs)" }, children: [option.icon ? _jsx(PhiIcon, { name: option.icon, size: 14 }) : null, option.label] }));
-                return (_jsx(Checkbox, { value: option.value, disabled: option.disabled, children: option.description ? _jsx(Tooltip, { title: option.description, children: content }) : content }, option.value));
-            }) }) }));
+    return (_jsx(Checkbox.Group, { value: [...(value ?? [])], disabled: disabled || readOnly || !onChange, onChange: (nextValue) => onChange?.(nextValue), style: { width: "100%" }, children: _jsx(Flex, { vertical: vertical, gap: "small", wrap: vertical ? false : "wrap", children: options.map((option) => (_jsx(Checkbox, { value: option.value, disabled: option.disabled, children: _jsx(PhiControlOptionContent, { option: option, presentation: "option" }) }, option.value))) }) }));
 }

package/components/controls/phi-collection-header-control.js

@@ -1,8 +1,8 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Tooltip, Typography } from "antd";
+import { Typography } from "antd";
 import { usePhiConfig } from "../root/phi-config-provider";
-import { PHI_DESCRIPTION_TOOLTIP_ICON } from "./phi-description-tooltip-icon";
+import { PhiDescriptionHint } from "./phi-description-tooltip-icon";
 export function PhiCollectionHeaderControl({ title, description, filters, toolbar, }) {
     const { token } = usePhiConfig();
     const hasTitle = title !== undefined && title !== null && title !== "";
@@ -23,13 +23,7 @@ export function PhiCollectionHeaderControl({ title, description, filters, toolba
                     gap: token.paddingXXS,
                     flex: "0 1 auto",
                     minWidth: 0,
-                }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, style: { minWidth: 0 }, children: title }), description ? (_jsx(Tooltip, { title: description, children: _jsx("span", { role: "img", "aria-label": "Information", tabIndex: 0, style: {
-                                display: "inline-flex",
-                                alignItems: "center",
-                                color: token.colorTextSecondary,
-                                cursor: "help",
-                                flex: "none",
-                            }, children: PHI_DESCRIPTION_TOOLTIP_ICON }) })) : null] })) : null, hasFilters ? (_jsx("div", { style: {
+                }, children: [_jsx(Typography.Text, { strong: true, ellipsis: true, style: { minWidth: 0 }, children: title }), description ? _jsx(PhiDescriptionHint, { description: description }) : null] })) : null, hasFilters ? (_jsx("div", { style: {
                     display: "flex",
                     alignItems: "flex-end",
                     flex: "1 1 280px",

package/components/controls/phi-collection-view-control.d.ts

@@ -18,6 +18,7 @@ export type PhiCollectionViewControlProps = {
         total: number;
         simple?: boolean;
         showSizeChanger?: boolean;
+        pageSizeOptions?: readonly number[];
         size?: PhiControlSize;
         onChange: (page: number, pageSize: number) => void;
     } | null;

package/components/controls/phi-collection-view-control.js

@@ -1,16 +1,16 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Skeleton } from "antd";
 import { usePhiConfig } from "../root/phi-config-provider";
 import { PhiCollectionHeaderControl } from "./phi-collection-header-control";
 import { PhiCollectionLayoutControl } from "./phi-collection-layout-control";
 import { PhiPaginationControl } from "./phi-pagination-control";
+import { PhiSkeletonControl } from "./phi-skeleton-control";
 export function PhiCollectionViewControl({ title, description, filters, toolbar, panel, diagnostics, body, items, mode = "grid", gap, minColumnWidth, pagination, }) {
     const { token } = usePhiConfig();
     const resolvedGap = gap ?? token.paddingSM;
-    return (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingSM, width: "100%", minWidth: 0 }, children: [_jsx(PhiCollectionHeaderControl, { title: title, description: description, filters: filters, toolbar: toolbar }), panel, diagnostics, body ?? (_jsx(PhiCollectionLayoutControl, { mode: mode, gap: resolvedGap, minColumnWidth: minColumnWidth ?? 102, items: [...(items ?? [])] })), pagination ? (_jsx("div", { style: { display: "flex", justifyContent: "flex-end", width: "100%", minWidth: 0 }, children: _jsx(PhiPaginationControl, { page: pagination.page, pageSize: pagination.pageSize, total: pagination.total, simple: pagination.simple, showSizeChanger: pagination.showSizeChanger, size: pagination.size, onChange: (value) => pagination.onChange(value.page, value.pageSize) }) })) : null] }));
+    return (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: token.paddingSM, width: "100%", minWidth: 0 }, children: [_jsx(PhiCollectionHeaderControl, { title: title, description: description, filters: filters, toolbar: toolbar }), panel, diagnostics, body ?? (_jsx(PhiCollectionLayoutControl, { mode: mode, gap: resolvedGap, minColumnWidth: minColumnWidth ?? 102, items: [...(items ?? [])] })), pagination ? (_jsx("div", { style: { display: "flex", justifyContent: "flex-end", width: "100%", minWidth: 0 }, children: _jsx(PhiPaginationControl, { page: pagination.page, pageSize: pagination.pageSize, total: pagination.total, simple: pagination.simple, showSizeChanger: pagination.showSizeChanger, pageSizeOptions: pagination.pageSizeOptions, size: pagination.size, onChange: (value) => pagination.onChange(value.page, value.pageSize) }) })) : null] }));
 }
 export function PhiCollectionViewSkeletonControl({ mode = "grid", gap, minColumnWidth, active = true, count = 8, }) {
     const { token } = usePhiConfig();
-    return (_jsx(PhiCollectionLayoutControl, { mode: mode, gap: gap ?? token.paddingSM, minColumnWidth: minColumnWidth ?? 102, items: Array.from({ length: count }, (_, index) => (_jsx(Skeleton.Node, { active: active, style: { width: "100%", minHeight: token.controlHeight * 3 } }, index))) }));
+    return (_jsx(PhiCollectionLayoutControl, { mode: mode, gap: gap ?? token.paddingSM, minColumnWidth: minColumnWidth ?? 102, items: Array.from({ length: count }, (_, index) => (_jsx(PhiSkeletonControl, { presentation: "node", active: active, style: { width: "100%", minHeight: token.controlHeight * 3 } }, index))) }));
 }