@phis/ui 0.2.1 → 0.3.0

package/plugins/runtime-modules/core/widgets/entry-header/config.js

@@ -0,0 +1,52 @@
+import { isPhiRecord } from "../../../../../helpers/is-record";
+import { resolvePhiCmsWidgetPluginKey } from "../../../../../constants/cms-widget-types";
+import { readPhiContentEntryRecordBinding } from "../../../../../helpers/content-entry-record-binding";
+import { phiContentEntryPartOptions, PhiContentEntryPart, readPhiContentEntryParts, } from "../../../../../constants/content-entry-parts";
+import { readRenderableBlockConfig, } from "../../../../../components/widgets/config/parser-primitives";
+/** Everything about an entry that is not its text: the parts a header can show. */
+const PHI_ENTRY_HEADER_PARTS = PhiContentEntryPart.Title | PhiContentEntryPart.Subtitle
+    | PhiContentEntryPart.Date | PhiContentEntryPart.Author | PhiContentEntryPart.Avatar
+    | PhiContentEntryPart.Category | PhiContentEntryPart.Tags;
+/** An article's opening: what it is filed under, its title and teaser, who wrote it and when. */
+const PHI_ENTRY_HEADER_DEFAULT_PARTS = PhiContentEntryPart.Title | PhiContentEntryPart.Subtitle
+    | PhiContentEntryPart.Date | PhiContentEntryPart.Author | PhiContentEntryPart.Avatar
+    | PhiContentEntryPart.Category;
+export function normalizePhiEntryHeaderWidgetConfig(config) {
+    const raw = isPhiRecord(config) ? config : {};
+    return {
+        ...readRenderableBlockConfig(raw),
+        entry: readPhiContentEntryRecordBinding(raw.entry),
+        show: readPhiContentEntryParts(raw.show, PHI_ENTRY_HEADER_PARTS, PHI_ENTRY_HEADER_DEFAULT_PARTS),
+        titleLevel: raw.titleLevel === "h2" ? "h2" : "h1",
+        align: raw.align === "center" ? "center" : "start",
+    };
+}
+export const PHI_ENTRY_HEADER_WIDGET_DEFINITION = {
+    kind: "widget",
+    pluginKey: resolvePhiCmsWidgetPluginKey("entry-header"),
+    typeKey: "entry-header",
+    title: "Entry header",
+    description: "The opening of one published entry: category, title, subtitle, author and date.",
+    category: "content",
+    tags: ["news", "blog", "content", "detail", "header", "author"],
+    icon: "antd:profile",
+    slotSizePolicy: "fill-inline",
+    fields: [
+        { key: "entry", type: "data-provider", providerKind: "record", label: "Entry" },
+        { key: "show", type: "flags", label: "Show", options: phiContentEntryPartOptions(PHI_ENTRY_HEADER_PARTS) },
+        {
+            key: "titleLevel",
+            type: "choice",
+            label: "Title level",
+            options: [{ value: "h1", label: "Page title (h1)" }, { value: "h2", label: "Section (h2)" }],
+        },
+        {
+            key: "align",
+            type: "choice",
+            label: "Alignment",
+            options: [{ value: "start", label: "Start" }, { value: "center", label: "Centre" }],
+        },
+    ],
+    defaultConfig: normalizePhiEntryHeaderWidgetConfig(null),
+    parseConfig: (config) => normalizePhiEntryHeaderWidgetConfig(config),
+};

package/plugins/runtime-modules/core/widgets/entry-header/plugin.d.ts

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

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

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { definePhiPassiveWidgetRenderers } from "../../../../../plugins/factories/widget-renderers";
+import { PHI_ENTRY_HEADER_WIDGET_DEFINITION } from "./config";
+import { PhiEntryHeaderWidget } from "./server";
+export const PHI_ENTRY_HEADER_WIDGET_PLUGIN = {
+    ...PHI_ENTRY_HEADER_WIDGET_DEFINITION,
+    ...definePhiPassiveWidgetRenderers(({ widget, config, runtime, registry }) => (_jsx(PhiEntryHeaderWidget, { config: config, runtime: runtime, registry: registry }, `widget-${widget.id}`))),
+};

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

@@ -0,0 +1,15 @@
+import type { PhiNoLabels, PhiServerBlockBaseProps } from "../../../../../types";
+import type { PhiCmsRuntimeRenderRegistry } from "../../../../../types/cms-plugins";
+import { type PhiEntryHeaderWidgetConfig } from "./config";
+export type PhiEntryHeaderWidgetProps = PhiServerBlockBaseProps<PhiNoLabels, PhiEntryHeaderWidgetConfig> & {
+    /** Where the record binding is answered; absent outside a page render, where nothing is bound. */
+    registry?: Pick<PhiCmsRuntimeRenderRegistry, "recordProviderLoadersByKey">;
+};
+/**
+ * The opening of one published entry, read while the page is drawn (`CONTENT_ENTRIES.md`).
+ *
+ * Through its record binding (`types/record-provider.ts`), like the body beside it: one Provider and the
+ * same parameters are answered once per request, so the two cost Core one read between them. Only the
+ * meta is prepared: the body is not parsed for a header.
+ */
+export declare function PhiEntryHeaderWidget({ config, runtime, registry }: PhiEntryHeaderWidgetProps): Promise<import("react").JSX.Element>;

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

@@ -0,0 +1,40 @@
+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 { phiRuntime } from "../../../../../server-helpers/phi-runtime";
+import { readPhiBoundContentEntry } from "../../content-entries/record-source.server";
+import { buildPhiEntryViews } from "../entry-list/view.server";
+import { normalizePhiEntryHeaderWidgetConfig } from "./config";
+/**
+ * The opening of one published entry, read while the page is drawn (`CONTENT_ENTRIES.md`).
+ *
+ * Through its record binding (`types/record-provider.ts`), like the body beside it: one Provider and the
+ * same parameters are answered once per request, so the two cost Core one read between them. Only the
+ * meta is prepared: the body is not parsed for a header.
+ */
+export async function PhiEntryHeaderWidget({ config, runtime, registry }) {
+    const settings = normalizePhiEntryHeaderWidgetConfig(config);
+    const rt = phiRuntime(runtime);
+    const labels = await getPhiContentEntryReaderLabels({
+        apiBaseUrl: rt.apiBaseUrl,
+        internalToken: rt.internalToken,
+        locale: runtime.locale.current,
+    });
+    const bound = await readPhiBoundContentEntry({ registry, runtime, binding: settings.entry });
+    if (bound.status === "unavailable") {
+        return _jsx(PhiAlertControl, { level: "warning", showIcon: true, title: labels.unavailable });
+    }
+    if (bound.status === "missing") {
+        return _jsx(PhiAlertControl, { level: "info", showIcon: true, title: labels.emptyTitle, description: labels.emptyText });
+    }
+    const [view] = await buildPhiEntryViews({
+        kind: bound.record.kind,
+        entries: [bound.record.entry],
+        runtime,
+        parts: settings.show,
+        body: "teaser",
+    });
+    return (_jsx(PhiRuntimeModuleRenderClientHost, { type: PhiCmsWidgetType.EntryHeader, componentProps: { entry: view, parts: settings.show, titleLevel: settings.titleLevel, align: settings.align } }));
+}

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

@@ -0,0 +1,2 @@
+import { type PhiEntryListWidgetConfig } from "./config";
+export declare const PHI_ENTRY_LIST_WIDGET_BUILDER_PLUGIN: import("../../../../../types").PhiCmsBuilderWidgetPlugin<PhiEntryListWidgetConfig>;

package/plugins/runtime-modules/{news/widgets/news-list → core/widgets/entry-list}/authoring.js

@@ -2,7 +2,7 @@
 import { Fragment as _Fragment, jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { createPhiCmsBuilderWidgetPlugin } from "../../../../../plugins/factories/widget-builder-plugin";
 import { PhiWidgetEditorPlaceholder } from "../../../../../components/widgets/builder/widget-editor-placeholder";
-import { PHI_NEWS_LIST_DEFAULT_LIMIT, PHI_NEWS_LIST_WIDGET_DEFINITION, } from "./config";
+import { PHI_ENTRY_LIST_DEFAULT_LIMIT, PHI_ENTRY_LIST_WIDGET_DEFINITION, } from "./config";
 /**
  * What the Builder says about a list whose entries it must not fetch.
  *
@@ -10,12 +10,12 @@ import { PHI_NEWS_LIST_DEFAULT_LIMIT, PHI_NEWS_LIST_WIDGET_DEFINITION, } from ".
  * here anyway: what appears is whatever is published and unexpired at the moment a visitor arrives. So
  * the editor states the settings it does own, and points at where the entries are written.
  */
-function PhiNewsListWidgetEditorSummary({ config }) {
-    const limit = config?.limit ?? PHI_NEWS_LIST_DEFAULT_LIMIT;
+function PhiEntryListWidgetEditorSummary({ config }) {
+    const limit = config?.limit ?? PHI_ENTRY_LIST_DEFAULT_LIMIT;
     const omitted = [
         config?.showTags === false ? "tags" : null,
         config?.showLinks === false ? "links" : null,
     ].filter((entry) => entry !== null);
-    return (_jsxs(_Fragment, { children: ["The ", limit, " most recent published news entries, read when the page is drawn", omitted.length > 0 ? _jsxs(_Fragment, { children: [" \u2014 without ", omitted.join(" or ")] }) : null, ". Entries are written in the Editor; what a visitor sees is whatever is published and has not expired."] }));
+    return (_jsxs(_Fragment, { children: ["The ", limit, " most recent published ", config?.kind ?? "news", " entries, read when the page is drawn", omitted.length > 0 ? _jsxs(_Fragment, { children: [" \u2014 without ", omitted.join(" or ")] }) : null, ". Entries are written in the Editor; what a visitor sees is whatever is published and has not expired."] }));
 }
-export const PHI_NEWS_LIST_WIDGET_BUILDER_PLUGIN = createPhiCmsBuilderWidgetPlugin(PHI_NEWS_LIST_WIDGET_DEFINITION, ({ widget, config }) => (_jsx(PhiWidgetEditorPlaceholder, { widget: widget, pluginTitle: PHI_NEWS_LIST_WIDGET_DEFINITION.title, summary: _jsx(PhiNewsListWidgetEditorSummary, { config: config ?? undefined }) })));
+export const PHI_ENTRY_LIST_WIDGET_BUILDER_PLUGIN = createPhiCmsBuilderWidgetPlugin(PHI_ENTRY_LIST_WIDGET_DEFINITION, ({ widget, config }) => (_jsx(PhiWidgetEditorPlaceholder, { widget: widget, pluginTitle: PHI_ENTRY_LIST_WIDGET_DEFINITION.title, summary: _jsx(PhiEntryListWidgetEditorSummary, { config: config ?? undefined }) })));

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

@@ -0,0 +1,95 @@
+import { type PhiMarkdownBlock } from "../../../../../components/widgets/shared/markdown-body-client";
+import type { PhiEntryListPresentation } from "./config";
+import type { PhiContentEntryReaderLabels } from "../../../../../components/widgets/label-sets/content-entries";
+/**
+ * One entry as the server prepared it.
+ *
+ * The date arrives formatted, not as an instant. It is formatted in the page's language, which only the
+ * server knows -- in the browser `Intl` would use the visitor's own locale, and on a Public page that is
+ * rendered once for everybody it would use the server's
+ * ([helpers/format-date-time.ts](../../../../../helpers/format-date-time.ts)). `machineDate` is the same
+ * moment for the `<time>` attribute, which is not language at all.
+ */
+export type PhiEntryListEntryView = {
+    id: string;
+    title: string;
+    subtitle: string;
+    /** The body, parsed on the server: Markdown never crosses this boundary as text. */
+    blocks: PhiMarkdownBlock[];
+    date: string;
+    machineDate: string;
+    /** Where "Read more" leads, resolved on the server; `null` where the entry has no link that resolves. */
+    link: {
+        href: string;
+        newTab: boolean;
+        external: boolean;
+    } | null;
+    /**
+     * The entry in a sentence or two: its subtitle, or where it has none the start of its first paragraph,
+     * in the page's language. What a card and a compact line show instead of the body.
+     */
+    teaser: string;
+    /** Where the title leads: the entry's detail Page, resolved on the server, or `null` for none. */
+    detail: {
+        href: string;
+        newTab: boolean;
+        external: boolean;
+    } | null;
+    /** The tags' labels in the page's language. */
+    tags: readonly string[];
+    /** The category's label, or `null` where the entry is filed under none. */
+    category: string | null;
+    /** The byline, or `null` where nobody is named. Never an address (`PhiSiteContentEntryAuthor`). */
+    author: {
+        name: string;
+        avatarUrl: string | null;
+    } | null;
+};
+export type PhiEntryListWidgetClientProps = {
+    entries: readonly PhiEntryListEntryView[];
+    labels: PhiContentEntryReaderLabels;
+    presentation: PhiEntryListPresentation;
+    /** Which parts of each entry show (`constants/content-entry-parts.ts`). */
+    parts: number;
+    /** The list's own heading, drawn only above entries -- an empty related list leaves no heading behind. */
+    title?: string;
+    /** Whether no entries is said or simply nothing: a related list under an entry says nothing. */
+    emptyBehavior?: "say" | "hide";
+};
+/**
+ * The parts of an entry that are about it rather than the text itself: tags, category, title, subtitle and
+ * byline -- each where the parts mask says so (`constants/content-entry-parts.ts`).
+ *
+ * Shared by the list, which puts the byline above the title the way a stream of entries reads, and the
+ * header of a detail Page, which sets it on the tags' line, flush right, so the title stands on its own;
+ * where the column is too narrow for both it wraps under the tags. The tags lead, as what the entry is filed
+ * under. The title is a link where the entry has a detail Page to lead to, which on that Page itself it
+ * does not.
+ */
+export declare function PhiEntryMeta({ entry, parts, titleLevel, byline, align, }: {
+    entry: PhiEntryListEntryView;
+    parts: number;
+    titleLevel?: 1 | 2 | 3;
+    byline?: "above" | "below" | "beside";
+    align?: "start" | "center";
+}): import("react").JSX.Element;
+/**
+ * The text of an entry: its body, and after it the tags and the link where the parts mask says so.
+ *
+ * The body through the Markdown Widget's own Client, not a second renderer: it already knows how to draw
+ * these blocks, including code, tables and internal links. No `tocKey` and no headings are passed, so it
+ * contributes nothing to the page's table of contents.
+ */
+export declare function PhiEntryBody({ entry, parts, labels, }: {
+    entry: PhiEntryListEntryView;
+    parts: number;
+    labels: PhiContentEntryReaderLabels;
+}): import("react").JSX.Element;
+/**
+ * The list itself, which holds no state and asks nothing.
+ *
+ * A Client half rather than markup from the server, because every visual Widget in this package renders
+ * through one: the Controls are where antd lives, and a server component cannot use them. Nothing here
+ * depends on the visitor, so the first paint already carries every entry.
+ */
+export declare function PhiEntryListWidgetClient({ entries, labels, presentation, parts, title, emptyBehavior, }: PhiEntryListWidgetClientProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,130 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { PhiAvatarControl } from "../../../../../components/controls/phi-avatar-control";
+import { PhiDividerControl } from "../../../../../components/controls/phi-divider-control";
+import { PhiEmptyControl } from "../../../../../components/controls/phi-empty-control";
+import { PhiFlexControl } from "../../../../../components/controls/phi-flex-control";
+import { PhiTagControl } from "../../../../../components/controls/phi-tag-control";
+import { PhiTypographyControl } from "../../../../../components/controls/phi-typography-control";
+import { PhiLink } from "../../../../../components/navigation/phi-link";
+import { PhiMarkdownWidgetClient, } from "../../../../../components/widgets/shared/markdown-body-client";
+import { PhiCollectionLayoutControl } from "../../../../../components/controls/phi-collection-layout-control";
+import { PhiCardWidgetClient } from "../../../../../components/widgets/shared/card-body-client";
+import { PHI_SURFACE_CARD } from "../../../../../helpers/surface-presets";
+import { PHI_FONT_SIZE, PHI_SPACE } from "../../../../../theme/antd-css-var-contract";
+import { hasPhiContentEntryPart, PhiContentEntryPart } from "../../../../../constants/content-entry-parts";
+/**
+ * How narrow a column of entry cards may get: the Card Collection's own floor, set by the shortest line
+ * of a teaser worth reading rather than by a thumbnail.
+ */
+const ENTRY_CARD_MIN_COLUMN_WIDTH = 260;
+/**
+ * One entry as a card: who and what above -- category and author at the start, the date at the end --
+ * then title, teaser, tags below, and the whole card leading to the entry's detail Page. The Card Widget's
+ * own card, so an entry looks like every other card of the Site.
+ */
+function PhiEntryCard({ entry, parts }) {
+    const eyebrow = [
+        hasPhiContentEntryPart(parts, PhiContentEntryPart.Category) ? entry.category : null,
+        hasPhiContentEntryPart(parts, PhiContentEntryPart.Author) ? entry.author?.name : null,
+    ].filter(Boolean).join(" · ");
+    const date = hasPhiContentEntryPart(parts, PhiContentEntryPart.Date) ? entry.date : "";
+    const meta = hasPhiContentEntryPart(parts, PhiContentEntryPart.Tags) && entry.tags.length > 0
+        ? entry.tags.join(" · ")
+        : "";
+    return (_jsx(PhiCardWidgetClient, { labels: {
+            eyebrow: eyebrow || undefined,
+            eyebrowEnd: date || undefined,
+            title: entry.title,
+            description: entry.teaser || undefined,
+            meta: meta || undefined,
+        }, config: {
+            surface: PHI_SURFACE_CARD,
+            ...(entry.detail ? { href: entry.detail.href, external: entry.detail.external } : {}),
+        } }));
+}
+/** One entry as a line: its date and title, and the teaser under them. */
+function PhiEntryLine({ entry, parts }) {
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.xxs, children: [_jsxs(PhiFlexControl, { gap: PHI_SPACE.xs, align: "baseline", wrap: true, children: [hasPhiContentEntryPart(parts, PhiContentEntryPart.Date) ? (_jsx(PhiTypographyControl, { presentation: "text", type: "secondary", children: _jsx("time", { dateTime: entry.machineDate, children: entry.date }) })) : null, _jsx(PhiTypographyControl, { presentation: "text", strong: true, children: entry.detail
+                            ? _jsx(PhiLink, { href: entry.detail.href, external: entry.detail.external, children: entry.title })
+                            : entry.title })] }), entry.teaser ? (_jsx(PhiTypographyControl, { presentation: "text", type: "secondary", ellipsis: true, children: entry.teaser })) : null] }));
+}
+/** What an entry is filed under, as quiet tags. */
+function PhiEntryTags({ tags }) {
+    return tags.length > 0 ? (_jsx(PhiFlexControl, { wrap: true, gap: PHI_SPACE.xxs, children: tags.map((tag) => (_jsx(PhiTagControl, { variant: "outlined", children: tag }, tag))) })) : null;
+}
+/**
+ * Who wrote it and when, on one line: the picture, the name, the date. Whichever of them the parts leave
+ * out, the rest closes up; with none of them there is no line.
+ */
+function PhiEntryByline({ entry, parts }) {
+    const author = hasPhiContentEntryPart(parts, PhiContentEntryPart.Author) ? entry.author : null;
+    const avatar = hasPhiContentEntryPart(parts, PhiContentEntryPart.Avatar) ? entry.author : null;
+    const date = hasPhiContentEntryPart(parts, PhiContentEntryPart.Date);
+    if (!author && !avatar && !date)
+        return null;
+    return (_jsxs(PhiFlexControl, { gap: PHI_SPACE.xs, align: "center", wrap: true, children: [avatar ? (_jsx(PhiAvatarControl, { size: 28, src: avatar.avatarUrl ?? undefined, alt: "", initialsFrom: avatar.name })) : null, _jsxs(PhiTypographyControl, { presentation: "text", type: "secondary", children: [author ? _jsxs(_Fragment, { children: [author.name, date ? " · " : null] }) : null, date ? _jsx("time", { dateTime: entry.machineDate, children: entry.date }) : null] })] }));
+}
+/**
+ * The parts of an entry that are about it rather than the text itself: tags, category, title, subtitle and
+ * byline -- each where the parts mask says so (`constants/content-entry-parts.ts`).
+ *
+ * Shared by the list, which puts the byline above the title the way a stream of entries reads, and the
+ * header of a detail Page, which sets it on the tags' line, flush right, so the title stands on its own;
+ * where the column is too narrow for both it wraps under the tags. The tags lead, as what the entry is filed
+ * under. The title is a link where the entry has a detail Page to lead to, which on that Page itself it
+ * does not.
+ */
+export function PhiEntryMeta({ entry, parts, titleLevel = 3, byline = "above", align = "start", }) {
+    const show = (part) => (parts & part) !== 0;
+    const bylineNode = _jsx(PhiEntryByline, { entry: entry, parts: parts });
+    const titleNode = show(PhiContentEntryPart.Title) ? (_jsx(PhiTypographyControl, { presentation: "title", level: titleLevel, style: { margin: 0, ...(align === "center" ? { textAlign: "center" } : {}) }, children: entry.detail
+            ? _jsx(PhiLink, { href: entry.detail.href, external: entry.detail.external, children: entry.title })
+            : entry.title })) : null;
+    const tagsNode = show(PhiContentEntryPart.Tags) && entry.tags.length > 0 ? _jsx(PhiEntryTags, { tags: entry.tags }) : null;
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.xs, align: align === "center" ? "center" : undefined, children: [byline === "beside" ? (_jsxs(PhiFlexControl, { justify: "space-between", align: "center", wrap: true, gap: PHI_SPACE.xs, children: [tagsNode ?? _jsx("span", {}), bylineNode] })) : tagsNode, show(PhiContentEntryPart.Category) && entry.category ? (_jsx(PhiTypographyControl, { presentation: "text", type: "secondary", strong: true, children: entry.category })) : null, byline === "above" ? bylineNode : null, titleNode, show(PhiContentEntryPart.Subtitle) && entry.subtitle ? (_jsx(PhiTypographyControl, { presentation: "text", strong: true, children: entry.subtitle })) : null, byline === "below" ? bylineNode : null] }));
+}
+/**
+ * The text of an entry: its body, and after it the tags and the link where the parts mask says so.
+ *
+ * The body through the Markdown Widget's own Client, not a second renderer: it already knows how to draw
+ * these blocks, including code, tables and internal links. No `tocKey` and no headings are passed, so it
+ * contributes nothing to the page's table of contents.
+ */
+export function PhiEntryBody({ entry, parts, labels, }) {
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.xs, children: [entry.blocks.length > 0 ? _jsx(PhiMarkdownWidgetClient, { config: { blocks: entry.blocks } }) : null, hasPhiContentEntryPart(parts, PhiContentEntryPart.Tags) ? _jsx(PhiEntryTags, { tags: entry.tags }) : null, hasPhiContentEntryPart(parts, PhiContentEntryPart.Link) && entry.link ? (_jsx(PhiLink, { href: entry.link.href, external: entry.link.external, newTab: entry.link.newTab, children: labels.readMore })) : null] }));
+}
+/**
+ * The parts a list entry's meta shows, and the one left for after its text. The tags lead with the byline
+ * on their line, the way a detail Page's header opens; only the link comes after the body.
+ */
+const ENTRY_META_PARTS = PhiContentEntryPart.Title | PhiContentEntryPart.Subtitle | PhiContentEntryPart.Date
+    | PhiContentEntryPart.Author | PhiContentEntryPart.Avatar | PhiContentEntryPart.Category
+    | PhiContentEntryPart.Tags;
+const ENTRY_BODY_PARTS = PhiContentEntryPart.Link;
+/** One entry whole, as a stream of entries shows it: tags and byline, title, then its text. */
+function PhiEntryArticle({ entry, labels, parts, }) {
+    return (_jsx("article", { children: _jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.xs, children: [_jsx(PhiEntryMeta, { entry: entry, parts: parts & ENTRY_META_PARTS, titleLevel: 2, byline: "beside" }), _jsx(PhiEntryBody, { entry: entry, parts: parts & ENTRY_BODY_PARTS, labels: labels })] }) }));
+}
+/**
+ * The list itself, which holds no state and asks nothing.
+ *
+ * A Client half rather than markup from the server, because every visual Widget in this package renders
+ * through one: the Controls are where antd lives, and a server component cannot use them. Nothing here
+ * depends on the visitor, so the first paint already carries every entry.
+ */
+export function PhiEntryListWidgetClient({ entries, labels, presentation, parts, title, emptyBehavior = "say", }) {
+    if (entries.length === 0) {
+        if (emptyBehavior === "hide")
+            return null;
+        return (_jsx(PhiEmptyControl, { description: (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.xxs, children: [_jsx(PhiTypographyControl, { presentation: "text", strong: true, children: labels.emptyTitle }), _jsx(PhiTypographyControl, { presentation: "text", type: "secondary", children: labels.emptyText })] })) }));
+    }
+    /*
+     * The list's own heading as a rule with its name at the start: under an entry it marks where the entry
+     * ends and the others begin, which a heading alone did not -- it stood as large as the text above it.
+     * Still an `h2`, in the rule, so the Page's outline keeps it.
+     */
+    const heading = title ? (_jsx(PhiDividerControl, { titlePlacement: "start", style: { margin: 0 }, children: _jsx(PhiTypographyControl, { presentation: "title", level: 2, style: { margin: 0, fontSize: PHI_FONT_SIZE.lg }, children: title }) })) : null;
+    const body = presentation === "cards" ? (_jsx(PhiCollectionLayoutControl, { mode: "grid", gap: PHI_SPACE.base, minColumnWidth: ENTRY_CARD_MIN_COLUMN_WIDTH, items: entries.map((entry) => _jsx(PhiEntryCard, { entry: entry, parts: parts }, entry.id)) })) : presentation === "compact" ? (_jsx(PhiFlexControl, { vertical: true, gap: PHI_SPACE.base, children: entries.map((entry) => _jsx(PhiEntryLine, { entry: entry, parts: parts }, entry.id)) })) : (_jsx(PhiFlexControl, { vertical: true, gap: PHI_SPACE.lg, children: entries.map((entry, index) => (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.lg, children: [index > 0 ? _jsx(PhiDividerControl, { style: { margin: 0 } }) : null, _jsx(PhiEntryArticle, { entry: entry, labels: labels, parts: parts })] }, entry.id))) }));
+    return heading ? (_jsxs(PhiFlexControl, { vertical: true, gap: PHI_SPACE.base, children: [heading, body] })) : body;
+}

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

@@ -0,0 +1,201 @@
+import { type PhiRuntimeDataProviderBinding } from "../../../../../types/runtime-data-provider";
+import { type PhiContentEntryKind } from "../../../../../constants/content-entry-kinds";
+import { type PhiLinkTarget } from "../../../../../types/references";
+import { PHI_ENTRY_LIST_DEFAULT_PARTS } from "../../../../../constants/content-entry-parts";
+import { type PhiCmsWidgetConfigBase } from "../../../../../components/widgets/config/parser-primitives";
+/**
+ * How the entries stand on the page (`CONTENT_ENTRIES.md`): `stack` is each entry whole, one under the
+ * next; `cards` a grid of cards, each leading to its entry's detail Page; `compact` one line of date and
+ * title with a teaser under it, for a sidebar or a home page.
+ */
+export declare const PHI_ENTRY_LIST_PRESENTATIONS: readonly ["stack", "cards", "compact"];
+export type PhiEntryListPresentation = (typeof PHI_ENTRY_LIST_PRESENTATIONS)[number];
+/**
+ * Where the entries come from: the newest of the kind, or the ones closest to one entry -- a "more like
+ * this" list under a detail Page, bound to that entry's record in `relatedTo`.
+ */
+export declare const PHI_ENTRY_LIST_SOURCES: readonly ["latest", "related"];
+export type PhiEntryListSource = (typeof PHI_ENTRY_LIST_SOURCES)[number];
+export { PHI_ENTRY_LIST_DEFAULT_PARTS };
+/** As many as a page can carry without becoming an archive, which is a later address. */
+export declare const PHI_ENTRY_LIST_DEFAULT_LIMIT = 10;
+export type PhiEntryListWidgetConfig = PhiCmsWidgetConfigBase & {
+    /** Which content kind's entries (`CONTENT_ENTRIES.md`). */
+    kind: PhiContentEntryKind;
+    /**
+     * Where an entry's title leads: the kind's detail route, a Page target the slug fills per entry
+     * (REFERENCES.md). Absent, or a route that does not resolve, and the titles are not links.
+     */
+    detailLinkTarget?: PhiLinkTarget;
+    presentation: PhiEntryListPresentation;
+    /**
+     * How many entries at most.
+     *
+     * A ceiling in the Widget rather than a page parameter: what a Site shows on its list page is a
+     * decision it makes once in the Builder, and a visitor who could ask for five hundred entries would be
+     * asking the server to render them.
+     */
+    limit: number;
+    /** Which parts of each entry show (`constants/content-entry-parts.ts`). */
+    show: number;
+    source: PhiEntryListSource;
+    /**
+     * Which categories a `latest` list shows, by id, and `none` for the entries filed under no category;
+     * empty is every entry. An id whose category was deleted since filters nothing -- it is left standing
+     * rather than swept, and a list left with only such ids shows every entry again.
+     *
+     * By id, not by address: a category renamed or given another address is still the one the list was
+     * set to (REFERENCES.md says the same of Pages).
+     */
+    categories: string[];
+    /**
+     * The entry a `related` list is about, as a record binding (`types/record-provider.ts`) -- the one the
+     * header and text above it are bound to, so the three share one read. A detail route's tree writes the
+     * route's slug into it; a list with no entry to be related to shows nothing.
+     */
+    relatedTo: PhiRuntimeDataProviderBinding | null;
+    /** A heading drawn above the entries, and only where there are any; empty for none. */
+    title: string;
+};
+export declare function normalizePhiEntryListWidgetConfig(config: unknown): PhiEntryListWidgetConfig;
+declare function parsePhiEntryListWidgetConfig(config: Record<string, unknown>): PhiEntryListWidgetConfig;
+export declare const PHI_ENTRY_LIST_WIDGET_DEFINITION: {
+    kind: "widget";
+    pluginKey: string;
+    typeKey: string;
+    title: string;
+    description: string;
+    category: "content";
+    tags: string[];
+    translatesOwnText: true;
+    icon: string;
+    slotSizePolicy: "fill-inline";
+    fields: ({
+        key: string;
+        type: "choice";
+        label: string;
+        options: {
+            value: string;
+            label: string;
+        }[];
+        heading?: undefined;
+        description?: undefined;
+        mode?: undefined;
+        placeholder?: undefined;
+        optionsProvider?: undefined;
+        visibleWhen?: undefined;
+        providerKind?: undefined;
+    } | {
+        key: string;
+        type: "link-target";
+        heading: string;
+        label: string;
+        options?: undefined;
+        description?: undefined;
+        mode?: undefined;
+        placeholder?: undefined;
+        optionsProvider?: undefined;
+        visibleWhen?: undefined;
+        providerKind?: undefined;
+    } | {
+        key: string;
+        type: "number";
+        label: string;
+        description: string;
+        options?: undefined;
+        heading?: undefined;
+        mode?: undefined;
+        placeholder?: undefined;
+        optionsProvider?: undefined;
+        visibleWhen?: undefined;
+        providerKind?: undefined;
+    } | {
+        key: string;
+        type: "flags";
+        label: string;
+        options: ({
+            readonly value: number;
+            readonly label: "Title";
+        } | {
+            readonly value: number;
+            readonly label: "Subtitle";
+        } | {
+            readonly value: number;
+            readonly label: "Date";
+        } | {
+            readonly value: number;
+            readonly label: "Author";
+        } | {
+            readonly value: number;
+            readonly label: "Author picture";
+        } | {
+            readonly value: number;
+            readonly label: "Category";
+        } | {
+            readonly value: number;
+            readonly label: "Tags";
+        } | {
+            readonly value: number;
+            readonly label: "Link";
+        })[];
+        heading?: undefined;
+        description?: undefined;
+        mode?: undefined;
+        placeholder?: undefined;
+        optionsProvider?: undefined;
+        visibleWhen?: undefined;
+        providerKind?: undefined;
+    } | {
+        key: string;
+        type: "choice";
+        mode: "multiple";
+        label: string;
+        description: string;
+        placeholder: string;
+        optionsProvider: {
+            providerKey: `${string}/${string}`;
+            params: {
+                noneValue: string;
+                categoryNoneLabel: string;
+            };
+        };
+        visibleWhen: {
+            field: string;
+            notEquals: string;
+            equals?: undefined;
+        };
+        options?: undefined;
+        heading?: undefined;
+        providerKind?: undefined;
+    } | {
+        key: string;
+        type: "data-provider";
+        providerKind: "record";
+        label: string;
+        description: string;
+        visibleWhen: {
+            field: string;
+            equals: string;
+            notEquals?: undefined;
+        };
+        options?: undefined;
+        heading?: undefined;
+        mode?: undefined;
+        placeholder?: undefined;
+        optionsProvider?: undefined;
+    } | {
+        key: string;
+        type: "string";
+        label: string;
+        options?: undefined;
+        heading?: undefined;
+        description?: undefined;
+        mode?: undefined;
+        placeholder?: undefined;
+        optionsProvider?: undefined;
+        visibleWhen?: undefined;
+        providerKind?: undefined;
+    })[];
+    defaultConfig: PhiEntryListWidgetConfig;
+    parseConfig: typeof parsePhiEntryListWidgetConfig;
+};