@phis/ui 0.2.1 → 0.4.0

package/plugins/runtime-modules/core/widgets/entry-list/plugin.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PhiCmsFlags } from "../../../../../constants/phi-cms";
+import { hasPhiFlag } from "../../../../../helpers/flags";
+import { definePhiPassiveWidgetRenderers } from "../../../../../plugins/factories/widget-renderers";
+import { PHI_ENTRY_LIST_WIDGET_DEFINITION } from "./config";
+import { PhiEntryListWidget } from "./server";
+export const PHI_ENTRY_LIST_WIDGET_PLUGIN = {
+    ...PHI_ENTRY_LIST_WIDGET_DEFINITION,
+    // `links` carries the detail route, resolved with every other target of the page before anything drew.
+    ...definePhiPassiveWidgetRenderers(({ widget, config, runtime, registry, links }) => (_jsx(PhiEntryListWidget, { config: config, runtime: runtime, registry: registry, links: links, translate: !hasPhiFlag(widget.flags, PhiCmsFlags.NoTranslate) }, `widget-${widget.id}`))),
+};

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

@@ -0,0 +1,27 @@
+import type { PhiNoLabels, PhiServerBlockBaseProps } from "../../../../../types";
+import type { PhiCmsRuntimeRenderRegistry } from "../../../../../types/cms-plugins";
+import type { PhiResolvedLinkTargets } from "../../../../../types/references";
+import { type PhiEntryListWidgetConfig } from "./config";
+export type PhiEntryListWidgetProps = PhiServerBlockBaseProps<PhiNoLabels, PhiEntryListWidgetConfig> & {
+    /** Where the record binding is answered; absent outside a page render, where nothing is bound. */
+    registry?: Pick<PhiCmsRuntimeRenderRegistry, "recordProviderLoadersByKey">;
+    links?: PhiResolvedLinkTargets | null;
+    /** Whether the heading is translated: the node's `NoTranslate` flag, read by the plugin. */
+    translate?: boolean;
+};
+/**
+ * One kind's published entries, read while the page is drawn (`CONTENT_ENTRIES.md`).
+ *
+ * Nothing here depends on the visitor -- published entries are the same for everybody -- so it belongs in
+ * the render rather than in a request the browser makes afterwards. On a Public page that is also the only
+ * way an expired entry can be absent instead of appearing and then disappearing.
+ *
+ * A failed read says so. The alternative is a page with a heading and nothing under it, which a visitor
+ * reads as "this Site has published nothing" and an operator cannot tell from the real thing.
+ *
+ * A `related` list is the exception twice over. It reads through its record binding, the one the header
+ * and text are bound to, so it costs Core nothing the Page did not already ask, and it is cut to as many
+ * as that record carries. And with nothing related -- or nothing to be related to -- it draws
+ * nothing at all: a "more like this" heading over an empty space says something false.
+ */
+export declare function PhiEntryListWidget({ config, runtime, registry, links, translate }: PhiEntryListWidgetProps): Promise<import("react").JSX.Element | null>;

package/plugins/runtime-modules/core/widgets/entry-list/server.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PhiAlertControl } from "../../../../../components/controls/phi-alert-control";
+import { PhiRuntimeModuleRenderClientHost } from "../../../../../components/runtime/runtime-module-render-client-manifest";
+import { getPhiContentEntryReaderLabels } from "../../../../../components/widgets/label-sets/content-entries";
+import { PhiCmsWidgetType } from "../../../../../constants/cms-widget-types";
+import { fetchPhiSiteContentEntries } from "../../../../../gateway/content-entries";
+import { phiRuntime } from "../../../../../server-helpers/phi-runtime";
+import { trBulk } from "../../../../../server-helpers/translate";
+import { readPhiBoundContentEntry } from "../../content-entries/record-source.server";
+import { buildPhiEntryViews } from "./view.server";
+import { normalizePhiEntryListWidgetConfig } from "./config";
+import { pickPhiSequenceSettings } from "../../../../../components/widgets/config/sequence-settings";
+/**
+ * One kind's published entries, read while the page is drawn (`CONTENT_ENTRIES.md`).
+ *
+ * Nothing here depends on the visitor -- published entries are the same for everybody -- so it belongs in
+ * the render rather than in a request the browser makes afterwards. On a Public page that is also the only
+ * way an expired entry can be absent instead of appearing and then disappearing.
+ *
+ * A failed read says so. The alternative is a page with a heading and nothing under it, which a visitor
+ * reads as "this Site has published nothing" and an operator cannot tell from the real thing.
+ *
+ * A `related` list is the exception twice over. It reads through its record binding, the one the header
+ * and text are bound to, so it costs Core nothing the Page did not already ask, and it is cut to as many
+ * as that record carries. And with nothing related -- or nothing to be related to -- it draws
+ * nothing at all: a "more like this" heading over an empty space says something false.
+ */
+export async function PhiEntryListWidget({ config, runtime, registry, links, translate = true }) {
+    const settings = normalizePhiEntryListWidgetConfig(config);
+    const rt = phiRuntime(runtime);
+    const locale = runtime.locale.current;
+    const labels = await getPhiContentEntryReaderLabels({
+        apiBaseUrl: rt.apiBaseUrl,
+        internalToken: rt.internalToken,
+        locale,
+    });
+    const related = settings.source === "related";
+    let kind = settings.kind;
+    let entries;
+    if (related) {
+        const bound = settings.relatedTo
+            ? await readPhiBoundContentEntry({ registry, runtime, binding: settings.relatedTo })
+            : null;
+        if (bound?.status !== "ok") {
+            return null;
+        }
+        kind = bound.record.kind;
+        entries = (bound.record.related ?? []).slice(0, settings.limit);
+    }
+    else {
+        try {
+            entries = await fetchPhiSiteContentEntries({
+                kind,
+                apiBaseUrl: rt.apiBaseUrl,
+                internalToken: rt.internalToken,
+                siteKey: rt.siteKey,
+                locale,
+                limit: settings.limit,
+                categories: settings.categories,
+            });
+        }
+        catch {
+            return _jsx(PhiAlertControl, { level: "warning", showIcon: true, title: labels.unavailable });
+        }
+    }
+    const views = await buildPhiEntryViews({
+        kind,
+        entries,
+        runtime,
+        parts: settings.show,
+        detailLinkTarget: settings.detailLinkTarget,
+        links,
+        body: settings.presentation === "stack" ? "full" : "teaser",
+        // A stacked entry's title is an `h2`; its text's headings start under it.
+        headingOffset: 2,
+    });
+    const [title] = settings.title && translate ? await trBulk([settings.title]) : [settings.title];
+    return (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiCmsWidgetType.EntryList, componentProps: {
+            entries: views,
+            labels,
+            presentation: settings.presentation,
+            ...(settings.presentation === "slideshow" ? { sequence: pickPhiSequenceSettings(settings) } : {}),
+            parts: settings.show,
+            ...(title ? { title } : {}),
+            emptyBehavior: related ? "hide" : "say",
+        } }));
+}

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

@@ -0,0 +1,33 @@
+import "server-only";
+import type { PhiContentEntryKind } from "../../../../../constants/content-entry-kinds";
+import type { PhiBlockRuntime } from "../../../../../types";
+import type { PhiSiteContentEntry } from "../../../../../types/content-entries";
+import type { PhiLinkTarget, PhiResolvedLinkTargets } from "../../../../../types/references";
+import type { PhiEntryListEntryView } from "./client";
+/**
+ * Entries as the entry Widgets draw them, prepared on the server: the body parsed and translated, the date
+ * formatted in the page's language, the links resolved.
+ *
+ * `parts` is the Widget's mask (`constants/content-entry-parts.ts`). Only what costs something follows it
+ * here -- an entry's link is resolved against the Page tree only where the link is shown; the rest is
+ * carried and the Client shows what the mask says.
+ */
+export declare function buildPhiEntryViews({ kind, entries, runtime, parts, detailLinkTarget, links, body: bodyMode, headingOffset, }: {
+    kind: PhiContentEntryKind;
+    entries: readonly PhiSiteContentEntry[];
+    runtime: PhiBlockRuntime;
+    parts: number;
+    /** The detail route each entry's title leads to, filled with its slug; absent on the detail Page. */
+    detailLinkTarget?: PhiLinkTarget;
+    links?: PhiResolvedLinkTargets | null;
+    /**
+     * `full` draws the body; `teaser` only needs what a card says, so a body is parsed and translated only
+     * where the entry has no subtitle to stand for it -- and then only for its first paragraph's sake.
+     */
+    body?: "full" | "teaser";
+    /**
+     * How far the text's headings move below the entry's title (`markdown-render.ts`): 1 under a detail
+     * Page's `h1`, 2 under a list's `h2`.
+     */
+    headingOffset?: number;
+}): Promise<PhiEntryListEntryView[]>;

package/plugins/runtime-modules/core/widgets/entry-list/view.server.js

@@ -0,0 +1,104 @@
+import "server-only";
+import { hasPhiContentEntryPart, PhiContentEntryPart } from "../../../../../constants/content-entry-parts";
+import { formatPhiDate } from "../../../../../helpers/format-date-time";
+import { collectPhiLinkTargetReferences, resolvePhiLinkHref } from "../../../../../helpers/link-target";
+import { resolvePhiLinkTargetReferences } from "../../../../../server-helpers/cms-link-targets";
+/** How long a teaser cut from the body may run: two lines of a card at the reading measure. */
+const TEASER_MAX_LENGTH = 200;
+function inlineText(inlines) {
+    return inlines.map((inline) => {
+        if (inline.kind === "text" || inline.kind === "inline_code")
+            return inline.text;
+        if (inline.kind === "break")
+            return " ";
+        if (inline.kind === "image")
+            return "";
+        return inlineText(inline.children);
+    }).join("");
+}
+/**
+ * The entry in a sentence or two: the subtitle where it has one, otherwise the start of the first
+ * paragraph -- read from the translated blocks, so a teaser is in the page's language like the body. Cut at
+ * a word, never in one.
+ */
+function readTeaser(subtitle, blocks) {
+    if (subtitle.trim())
+        return subtitle.trim();
+    const paragraph = blocks.find((block) => block.kind === "paragraph");
+    const text = paragraph?.kind === "paragraph" ? inlineText(paragraph.inlines).replace(/\s+/gu, " ").trim() : "";
+    if (text.length <= TEASER_MAX_LENGTH)
+        return text;
+    const cut = text.slice(0, TEASER_MAX_LENGTH);
+    const lastSpace = cut.lastIndexOf(" ");
+    return `${(lastSpace > TEASER_MAX_LENGTH / 2 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+/**
+ * Entries as the entry Widgets draw them, prepared on the server: the body parsed and translated, the date
+ * formatted in the page's language, the links resolved.
+ *
+ * `parts` is the Widget's mask (`constants/content-entry-parts.ts`). Only what costs something follows it
+ * here -- an entry's link is resolved against the Page tree only where the link is shown; the rest is
+ * carried and the Client shows what the mask says.
+ */
+export async function buildPhiEntryViews({ kind, entries, runtime, parts, detailLinkTarget, links, body: bodyMode = "full", headingOffset = 1, }) {
+    const showLinks = hasPhiContentEntryPart(parts, PhiContentEntryPart.Link);
+    const settings = { kind, showLinks, detailLinkTarget };
+    const locale = runtime.locale.current;
+    /*
+     * The body is Markdown, and it is parsed and translated here rather than answered translated by Core.
+     *
+     * Only the inline content of headings, paragraphs and table cells is handed to a provider, as HTML --
+     * the structure, code fences and raw HTML never are (`collectMarkdownTranslationUnits`). That is what
+     * makes Markdown the right standard for an entry: the control characters are not spared, they are never
+     * sent. It also means each paragraph is its own cache entry, so correcting one costs one.
+     *
+     * The entry's own language and switch decide, not the Widget's: they belong to the words.
+     */
+    /*
+     * Imported here rather than at the top: the Widget catalogue loads every Module's server file at
+     * start-up, and reaching into the core Module's graph from there closes a cycle through its data
+     * provider keys -- eleven unrelated suites failed on an undefined constant before this moved inside.
+     */
+    const { resolveMarkdownRenderData } = await import("../../../../../components/widgets/shared/markdown-render");
+    /*
+     * Every entry's Page in one question, the way a render resolves its Widgets' links: a Page that is gone
+     * or unpublished resolves to nothing, and the entry then shows no link rather than one to nowhere.
+     */
+    const resolvedLinks = settings.showLinks
+        ? await resolvePhiLinkTargetReferences(collectPhiLinkTargetReferences(entries.map((entry) => ({ linkTarget: entry.link }))), runtime)
+        : null;
+    const views = await Promise.all(entries.map(async (entry, index) => {
+        // Core answers the slug where an entry has one; the index is the fallback for an entry that has
+        // none, so two entries can never share a React key -- or a heading anchor.
+        const id = entry.id || entry.slug || `${settings.kind}-${index}`;
+        const needsBody = bodyMode === "full" || !entry.subtitle.trim();
+        const body = needsBody && entry.content.trim()
+            ? await resolveMarkdownRenderData({
+                sourceMode: "inline",
+                markdown: entry.content,
+                translate: entry.translate,
+                sourceLocale: entry.sourceLocale ?? undefined,
+                widgetId: `${settings.kind}-${id}`,
+                // A teaser is the first paragraph; the rest is neither drawn nor translated.
+                extent: bodyMode === "full" ? "document" : "first-paragraph",
+                headingOffset,
+            }, runtime)
+            : { blocks: [] };
+        return {
+            id,
+            title: entry.title,
+            subtitle: entry.subtitle,
+            blocks: bodyMode === "full" && !("error" in body) ? body.blocks : [],
+            teaser: readTeaser(entry.subtitle, "error" in body ? [] : body.blocks),
+            date: formatPhiDate(entry.created, locale),
+            machineDate: entry.created,
+            link: settings.showLinks ? resolvePhiLinkHref(entry.link, resolvedLinks) : null,
+            // The kind's detail route with this entry's slug; no route that resolves, no link on the title.
+            detail: entry.slug ? resolvePhiLinkHref(settings.detailLinkTarget, links, { slug: entry.slug }) : null,
+            tags: entry.tags.map((tag) => tag.label),
+            category: entry.category?.label ?? null,
+            author: entry.author ? { name: entry.author.name, avatarUrl: entry.author.avatar?.url ?? null } : null,
+        };
+    }));
+    return views;
+}

package/plugins/runtime-modules/core/widgets/float-button/authoring.d.ts

@@ -0,0 +1,3 @@
+import type { PhiCmsBuilderWidgetPlugin } from "../../../../../types";
+import { type PhiFloatButtonWidgetConfig } from "./config";
+export declare const PHI_FLOAT_BUTTON_WIDGET_BUILDER_PLUGIN: PhiCmsBuilderWidgetPlugin<PhiFloatButtonWidgetConfig>;

package/plugins/runtime-modules/core/widgets/float-button/authoring.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PhiFloatButtonWidget } from "./client";
+import { PHI_FLOAT_BUTTON_BOUNDS, PHI_FLOAT_BUTTON_WIDGET_DEFINITION, } from "./config";
+import { filterPhiCommandButtonsForViewer } from "../../../../../components/widgets/config/command-buttons";
+import { PHI_COMMON_CONTROL_DEFAULT_LABELS } from "../../../../../components/widgets/label-types/common-controls";
+import { PhiCommandButtonsAuthoringTools } from "../../../../../components/widgets/client/shared/phi-command-buttons-authoring-tools";
+export const PHI_FLOAT_BUTTON_WIDGET_BUILDER_PLUGIN = {
+    ...PHI_FLOAT_BUTTON_WIDGET_DEFINITION,
+    /* In its slot, not in the corner: fixed, it would float over the editor and could not be selected. */
+    renderEditor: ({ widget, config, runtime, registry }) => (_jsx(PhiFloatButtonWidget, { blockId: widget.id, config: {
+            ...config,
+            buttons: filterPhiCommandButtonsForViewer(config.buttons, runtime.viewer, registry?.roleProviderIdByWidgetType.get(widget.widgetType)),
+        }, labels: PHI_COMMON_CONTROL_DEFAULT_LABELS, inPlace: true })),
+    renderEditorTools: ({ config, authoring }) => authoring?.updateConfig ? (_jsx(PhiCommandButtonsAuthoringTools, { buttons: config.buttons, bounds: PHI_FLOAT_BUTTON_BOUNDS, onChange: (buttons) => authoring.updateConfig?.({ buttons }) })) : null,
+};

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

@@ -0,0 +1,12 @@
+import type { PhiFloatButtonWidgetConfig } from "./config";
+import type { PhiCmsInstanceId } from "../../../../../types/cms-instance-id";
+import type { PhiCommonControlLabels } from "../../../../../components/widgets/label-types/common-controls";
+export declare function PhiFloatButtonWidget({ config, blockId, labels, disabled, signalsEnabled, inPlace, }: {
+    config?: PhiFloatButtonWidgetConfig | null;
+    blockId?: PhiCmsInstanceId | null;
+    labels?: PhiCommonControlLabels | null;
+    disabled?: boolean;
+    signalsEnabled?: boolean;
+    /** Drawn in its slot rather than fixed to the viewport: the Builder's canvas and the preview. */
+    inPlace?: boolean;
+}): import("react").JSX.Element;

package/plugins/runtime-modules/core/widgets/float-button/client.js

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { usePhiCommandButtons } from "../../../../../components/widgets/client/shared/phi-command-buttons";
+import { PhiFloatButtonControl } from "../../../../../components/controls/phi-float-button-control";
+/* One empty list, so a Float Button without config does not hand the buttons a new identity every render. */
+const NO_BUTTONS = [];
+function toCssLength(value) {
+    return typeof value === "number" ? `${value}px` : value;
+}
+export function PhiFloatButtonWidget({ config, blockId, labels, disabled, signalsEnabled = true, inPlace = false, }) {
+    const commands = usePhiCommandButtons({
+        buttons: config?.buttons ?? NO_BUTTONS,
+        signalRoutes: config?.signalRoutes,
+        blockId,
+        labels,
+        disabled,
+        signalsEnabled,
+    });
+    return (_jsx(PhiFloatButtonControl, { items: commands.items, placement: config?.placement, offset: { block: toCssLength(config?.offsetBlock), inline: toCssLength(config?.offsetInline) }, shape: config?.shape, group: {
+            trigger: config?.groupTrigger,
+            icon: config?.groupIcon,
+            direction: config?.groupDirection,
+        }, inPlace: inPlace, disabled: commands.disabled, onActivate: commands.activate }));
+}

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

@@ -0,0 +1,97 @@
+import type { PhiCommandButtonConfig } from "../../../../../types/core-widget-placements";
+import { type PhiCssLength } from "../../../../../types/length";
+import { type PhiCmsWidgetConfigBase } from "../../../../../components/widgets/config/parser-primitives";
+import { type PhiControlConfig } from "../../../../../components/widgets/config/control-signal-config";
+import type { PhiFloatButtonControlGroup, PhiFloatButtonControlPlacement } from "../../../../../components/controls/phi-float-button-control";
+/**
+ * Buttons that stay in a corner of the viewport while the Page scrolls: one, or a group of them.
+ *
+ * The buttons are the Command Toolbar's -- the same fields, the same subcontrol addresses, the same
+ * runtime -- and only how they stand is this Widget's. It sits in a slot of the Page it belongs to and
+ * takes no room there; a Float Button for every Page of an Area is the Area's Pages each placing one.
+ */
+export type PhiFloatButtonWidgetConfig = PhiCmsWidgetConfigBase & PhiControlConfig & {
+    buttons: PhiCommandButtonConfig[];
+    placement?: PhiFloatButtonControlPlacement;
+    offsetBlock?: PhiCssLength;
+    offsetInline?: PhiCssLength;
+    shape?: "circle" | "square";
+    groupTrigger?: NonNullable<PhiFloatButtonControlGroup["trigger"]>;
+    groupIcon?: string;
+    groupDirection?: NonNullable<PhiFloatButtonControlGroup["direction"]>;
+};
+declare function parsePhiFloatButtonWidgetConfig(config: Record<string, unknown>): PhiFloatButtonWidgetConfig;
+/** A corner holds fewer buttons than a toolbar: past six, a group covers the Page it floats over. */
+export declare const PHI_FLOAT_BUTTON_BOUNDS: {
+    min: number;
+    max: number;
+};
+export declare const PHI_FLOAT_BUTTON_WIDGET_DEFINITION: {
+    kind: "widget";
+    pluginKey: string;
+    typeKey: string;
+    title: string;
+    description: string;
+    category: "form";
+    icon: string;
+    iconFamily: string;
+    slotSizePolicy: "intrinsic";
+    runtimeSignals: {
+        emits: {
+            id: string;
+            action: "activate";
+            valueType: "string";
+            target: "subcontrol";
+        }[];
+        listens: ({
+            readonly target: "subcontrol";
+            readonly id: "enabled";
+            readonly channel: "enabled";
+            readonly action: "change";
+            readonly valueType: "boolean";
+        } | {
+            id: string;
+            channel: string;
+            action: "change";
+            valueType: "boolean";
+            target: "subcontrol";
+        } | {
+            id: string;
+            channel: string;
+            action: "change";
+            valueType: "string";
+            target: "subcontrol";
+        } | {
+            id: string;
+            channel: string;
+            action: "change";
+            valueType: "number";
+            target: "subcontrol";
+        } | {
+            id: string;
+            channel: string;
+            action: "change";
+            valueType: "icon";
+            target: "subcontrol";
+        })[];
+    };
+    signalSubcontrols: {
+        configKey: string;
+        keyField: string;
+        labelFields: string[];
+        labelFieldValues: {
+            action: {
+                [k: string]: string;
+            };
+        };
+    }[];
+    fields: import("../../../../../types").PhiCmsConfigField[];
+    defaultConfig: {
+        key: string;
+        placement: "bottom-end";
+        shape: "circle";
+        buttons: PhiCommandButtonConfig[];
+    };
+    parseConfig: typeof parsePhiFloatButtonWidgetConfig;
+};
+export {};

package/plugins/runtime-modules/core/widgets/float-button/config.js

@@ -0,0 +1,129 @@
+import { resolvePhiCmsWidgetPluginKey } from "../../../../../constants/cms-widget-types";
+import { readPhiLengthValue } from "../../../../../types/length";
+import { PHI_COMMAND_CONTROL_SIGNALS } from "../../../../../components/widgets/signals/control-signal-capabilities";
+import { readRenderableBlockConfig, readString, } from "../../../../../components/widgets/config/parser-primitives";
+import { parsePhiControlConfig, } from "../../../../../components/widgets/config/control-signal-config";
+import { PHI_COMMAND_BUTTONS_SIGNAL_SUBCONTROLS, buildPhiCommandButtonsField, createPhiCommandButton, readPhiCommandButtons, } from "../../../../../components/widgets/config/command-buttons";
+const PHI_FLOAT_BUTTON_PLACEMENTS = ["bottom-end", "bottom-start", "top-end", "top-start"];
+const PHI_FLOAT_BUTTON_GROUP_DIRECTIONS = ["top", "bottom", "left", "right"];
+function readOneOf(value, allowed) {
+    const text = readString(value);
+    return allowed.includes(text ?? "") ? text : undefined;
+}
+function parsePhiFloatButtonWidgetConfig(config) {
+    return {
+        ...readRenderableBlockConfig(config),
+        ...parsePhiControlConfig(config, { key: "float" }),
+        buttons: readPhiCommandButtons(config.buttons),
+        placement: readOneOf(config.placement, PHI_FLOAT_BUTTON_PLACEMENTS) ?? "bottom-end",
+        offsetBlock: readPhiLengthValue(config.offsetBlock) ?? undefined,
+        offsetInline: readPhiLengthValue(config.offsetInline) ?? undefined,
+        shape: readString(config.shape) === "square" ? "square" : "circle",
+        groupTrigger: readOneOf(config.groupTrigger, ["click", "hover"]),
+        groupIcon: readString(config.groupIcon),
+        groupDirection: readOneOf(config.groupDirection, PHI_FLOAT_BUTTON_GROUP_DIRECTIONS),
+    };
+}
+/** The entry fields offered only while the Float Button is square, read from the Widget around them. */
+const PHI_FLOAT_BUTTON_SQUARE = { field: "shape", scope: "parent", equals: "square" };
+/** A corner holds fewer buttons than a toolbar: past six, a group covers the Page it floats over. */
+export const PHI_FLOAT_BUTTON_BOUNDS = { min: 1, max: 6 };
+export const PHI_FLOAT_BUTTON_WIDGET_DEFINITION = {
+    kind: "widget",
+    pluginKey: resolvePhiCmsWidgetPluginKey("float-button"),
+    typeKey: "float-button",
+    title: "Float Button",
+    description: "Buttons fixed to a corner of the viewport, alone or as a group, emitting configured commands.",
+    category: "form",
+    icon: "antd:plus-circle-outlined",
+    iconFamily: "form",
+    slotSizePolicy: "intrinsic",
+    runtimeSignals: {
+        ...PHI_COMMAND_CONTROL_SIGNALS,
+    },
+    signalSubcontrols: PHI_COMMAND_BUTTONS_SIGNAL_SUBCONTROLS,
+    fields: [
+        /*
+         * The buttons first, as on the Command Toolbar, and what holds for all of them below. A label only
+         * where there is room for one: a round button is its icon, and the label it keeps names it in the
+         * select and the Signals panel and becomes its tooltip. No danger, which Ant Design's Float Button
+         * does not draw.
+         */
+        buildPhiCommandButtonsField({
+            omit: ["danger"],
+            labelVisibleWhen: PHI_FLOAT_BUTTON_SQUARE,
+            extraItemFields: [
+                {
+                    key: "display",
+                    type: "choice",
+                    label: "Display",
+                    visibleWhen: PHI_FLOAT_BUTTON_SQUARE,
+                    emptyOption: { value: "", label: "Icon", separator: "after" },
+                    emptyValue: undefined,
+                    options: [
+                        { value: "icon-label", label: "Icon and label" },
+                        { value: "label", label: "Label" },
+                    ],
+                },
+            ],
+        }),
+        {
+            key: "placement",
+            type: "choice",
+            label: "Corner",
+            heading: "Floating",
+            options: [
+                { value: "bottom-end", label: "Bottom end" },
+                { value: "bottom-start", label: "Bottom start" },
+                { value: "top-end", label: "Top end" },
+                { value: "top-start", label: "Top start" },
+            ],
+        },
+        { key: "offsetBlock", type: "length", label: "Distance from top or bottom", min: 0 },
+        { key: "offsetInline", type: "length", label: "Distance from the side", min: 0 },
+        {
+            key: "shape",
+            type: "choice",
+            label: "Shape",
+            options: [
+                { value: "circle", label: "Circle" },
+                { value: "square", label: "Square" },
+            ],
+        },
+        /* The group's own settings; a single button has no group to open. */
+        {
+            key: "groupTrigger",
+            type: "choice",
+            label: "Group opens",
+            heading: "Group",
+            emptyOption: { value: "", label: "Always open", separator: "after" },
+            emptyValue: undefined,
+            options: [
+                { value: "click", label: "On click" },
+                { value: "hover", label: "On hover" },
+            ],
+        },
+        { key: "groupIcon", type: "icon", label: "Group icon", visibleWhen: { field: "groupTrigger", notEquals: null } },
+        {
+            key: "groupDirection",
+            type: "choice",
+            label: "Unfolds",
+            emptyOption: { value: "", label: "Away from the edge", separator: "after" },
+            emptyValue: undefined,
+            options: [
+                { value: "top", label: "Up" },
+                { value: "bottom", label: "Down" },
+                { value: "left", label: "Left" },
+                { value: "right", label: "Right" },
+            ],
+        },
+    ],
+    defaultConfig: {
+        key: "float",
+        placement: "bottom-end",
+        shape: "circle",
+        /* One to start with, so a Float Button just placed is something to see and to select. */
+        buttons: [createPhiCommandButton([])],
+    },
+    parseConfig: parsePhiFloatButtonWidgetConfig,
+};

package/plugins/runtime-modules/core/widgets/float-button/plugin.d.ts

@@ -0,0 +1,3 @@
+import type { PhiCmsWidgetPlugin } from "../../../../../types";
+import { type PhiFloatButtonWidgetConfig } from "./config";
+export declare const PHI_FLOAT_BUTTON_WIDGET_PLUGIN: PhiCmsWidgetPlugin<PhiFloatButtonWidgetConfig>;

package/plugins/runtime-modules/core/widgets/float-button/plugin.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PhiCmsWidgetType } from "../../../../../constants/cms-widget-types";
+import { PhiRuntimeModuleRenderClientHost } from "../../../../../components/runtime/runtime-module-render-client-manifest";
+import { filterPhiCommandButtonsForViewer } from "../../../../../components/widgets/config/command-buttons";
+import { getPhiCommonControlLabelsForRuntime } from "../../../../../components/widgets/label-sets/common-controls";
+import { PHI_FLOAT_BUTTON_WIDGET_DEFINITION, } from "./config";
+export const PHI_FLOAT_BUTTON_WIDGET_PLUGIN = {
+    ...PHI_FLOAT_BUTTON_WIDGET_DEFINITION,
+    render: async ({ widget, config, runtime, registry }) => (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiCmsWidgetType.FloatButton, componentProps: {
+            blockId: widget.id,
+            config: {
+                ...config,
+                buttons: filterPhiCommandButtonsForViewer(config.buttons, runtime.viewer, registry?.roleProviderIdByWidgetType.get(widget.widgetType)),
+            },
+            labels: await getPhiCommonControlLabelsForRuntime(runtime),
+        } })),
+    /* A preview shows the buttons where the Widget stands; fixed, they would float over whatever frames it. */
+    renderPreview: async ({ widget, config, runtime, registry }) => (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiCmsWidgetType.FloatButton, componentProps: {
+            blockId: widget.id,
+            config: {
+                ...config,
+                buttons: filterPhiCommandButtonsForViewer(config.buttons, runtime.viewer, registry?.roleProviderIdByWidgetType.get(widget.widgetType)),
+            },
+            labels: await getPhiCommonControlLabelsForRuntime(runtime),
+            disabled: true,
+            signalsEnabled: false,
+            inPlace: true,
+        } })),
+};

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

@@ -6,6 +6,7 @@ export declare const PHI_FORM_WIDGET_DEFINITION: {
     title: string;
     category: "form";
     description: string;
+    icon: string;
     iconFamily: string;
     slotSizePolicy: "fill-inline";
     requiredRuntimeControllers: import("../../../../../types").PhiCmsWidgetRuntimeControllerRequirementResolver<PhiCmsFormWidgetConfig>;
@@ -179,7 +180,6 @@ export declare const PHI_FORM_WIDGET_DEFINITION: {
         maxFormWidth: 610;
         formId: null;
         submit: "external";
-        submitOnEnter: false;
         links: never[];
         formConfig: {};
         execution: {