@phis/ui 0.2.1 → 0.3.0

package/components/widgets/label-types/revisions.js

@@ -25,6 +25,11 @@ export const PHI_BUILDER_REVISIONS_WIDGET_DEFAULT_LABELS = {
         pageSaved: "Saved page draft from revision %1",
         areaNodesChanged: "Changed %1 nodes from revision %2",
         areaSaved: "Saved area draft from revision %1",
+        areaModulesChanged: "Modules changed: %1 from revision %2",
+        areaModulesSaved: "Saved module selection from revision %1",
+        moduleAdded: "+ %1",
+        moduleRemoved: "− %1",
+        lastSaved: "%1 · last saved %2 by %3",
         navigationOverlayChanged: "Changed navigation overlay (%1 overrides, %2 hidden) from revision %3",
         navigationSaved: "Saved navigation draft from revision %1",
         themeChanged: "Based on %1 v%2, %3 custom overrides from revision %4",
@@ -47,14 +52,17 @@ export const PHI_BUILDER_REVISIONS_WIDGET_DEFAULT_LABELS = {
         restore: "Restore",
         delete: "Delete",
         deleteSelected: "Delete selected",
-        deleteArea: "Delete Area",
+        deleteArea: "Clear Area",
+        resetPage: "Reset to preset",
+        resetPageUnavailable: "Only a Module's Page has a preset to go back to. Choose one under Page.",
     },
     deleteArea: {
-        title: "Delete this Area's shell?",
-        survives: "The Area keeps its Pages, its Navigation and its Theme. Only the shell goes.",
+        title: "Clear this Area back to its preset?",
+        warning: "Everything this Site stored for the Area is cleared -- its Shell and its Module selection, drafts and published alike. What is live changes at once, the Module preset takes the Area back, and no revision is left to restore it from. It cannot be undone.",
+        survives: "The Area keeps its Pages, its Navigation and its Theme. Its Shell and its Module selection go back to the preset.",
         field: "Type the Area key to confirm",
         fieldRequired: "Write the Area key out to confirm.",
-        confirm: "Delete Area",
+        confirm: "Clear Area",
         cancel: "Cancel",
     },
     confirm: {
@@ -64,5 +72,7 @@ export const PHI_BUILDER_REVISIONS_WIDGET_DEFAULT_LABELS = {
         deleteDescription: "Revisions are deleted permanently.",
         deleteSelectedTitle: "Delete %1 selected revisions?",
         deleteSelectedDescription: "Selected revisions are deleted permanently.",
+        resetPageTitle: "Take this Page back to its Module's preset?",
+        resetPageDescription: "The Site's own version of this Page is deleted with all its revisions, and the Module's preset is live at once. Texts written for the preset's own blocks stay.",
     },
 };

package/components/widgets/label-types/theme-mode-switch.d.ts

@@ -0,0 +1,5 @@
+export type PhiThemeModeSwitchWidgetLabels = {
+    switchToDark: string;
+    switchToLight: string;
+};
+export declare const PHI_THEME_MODE_SWITCH_WIDGET_DEFAULT_LABELS: PhiThemeModeSwitchWidgetLabels;

package/components/widgets/label-types/theme-mode-switch.js

@@ -0,0 +1,4 @@
+export const PHI_THEME_MODE_SWITCH_WIDGET_DEFAULT_LABELS = {
+    switchToDark: "Switch to dark mode",
+    switchToLight: "Switch to light mode",
+};

package/components/widgets/label-types/tour.d.ts

@@ -0,0 +1,9 @@
+import type { PhiTourLabels } from "../../../types/tours";
+/** The words around every Tour, and the button that starts one. */
+export type PhiTourWidgetLabels = PhiTourLabels & {
+    /** The button's own word. */
+    button: string;
+    /** What pressing it does, as its tooltip. */
+    start: string;
+};
+export declare const PHI_TOUR_WIDGET_DEFAULT_LABELS: PhiTourWidgetLabels;

package/components/widgets/label-types/tour.js

@@ -0,0 +1,7 @@
+export const PHI_TOUR_WIDGET_DEFAULT_LABELS = {
+    next: "Next",
+    previous: "Back",
+    finish: "Done",
+    button: "Tour",
+    start: "Start the tour of the page",
+};

package/components/widgets/login-redirect.d.ts

@@ -1,3 +1,3 @@
+/** Where to go after signing in, if it is an address on this Site (helpers/internal-path.ts). */
 export declare function normalizeLoginRedirectTarget(value: string | null | undefined): string | null;
-export declare function resolvePostLoginTarget(pathname: string, locale: string, area: string): string;
 export declare function resolveSafePostLoginTarget(pathname: string, locale: string, area: string): Promise<string>;

package/components/widgets/login-redirect.js

@@ -1,13 +1,11 @@
 import { requestPhiJson } from "../../helpers/client-json-request";
+import { readPhiInternalPath } from "../../helpers/internal-path";
 import { localizeAreaPath, localizePath, stripLocaleAndAreaFromPathname } from "../../helpers/locale";
+/** Where to go after signing in, if it is an address on this Site (helpers/internal-path.ts). */
 export function normalizeLoginRedirectTarget(value) {
-    const normalized = value?.trim() ?? "";
-    if (!normalized || !normalized.startsWith("/") || normalized.startsWith("//")) {
-        return null;
-    }
-    return normalized;
+    return readPhiInternalPath(value);
 }
-export function resolvePostLoginTarget(pathname, locale, area) {
+function resolvePostLoginTarget(pathname, locale, area) {
     const publicPath = stripLocaleAndAreaFromPathname(pathname) || "/";
     const isBootstrapAuthPath = publicPath === "/login" || publicPath === "/confirm" || publicPath === "/reset-password";
     if (area === "public") {

package/components/widgets/navigation-descriptor-resolver.server.js

@@ -2,13 +2,27 @@
 import { isPhiCmsNavigationOverlayTarget, readPhiCmsNavigationTargetPath, } from "../../helpers/navigation-target";
 import { createPhiPresetCmsInstanceId } from "../../types/cms-instance-id";
 import { createGlobalTranslator, createSiteTranslator, PHI_TR_CTX_WEB_UI_LABEL, } from "../../gateway/tr";
-import { resolvePhiCmsNavigationOverlay, resolvePhiCmsActiveNavigationSurfaces, resolvePhiCmsRouteDescriptorByPageId, } from "../../plugins/runtime-modules/descriptor-compiler";
+import { resolvePhiCmsNavigationOverlay, resolvePhiCmsActiveNavigationSurfaces, resolvePhiCmsRoutePresetByPageId, } from "../../plugins/runtime-modules/descriptor-compiler";
+import { logRuntimeEvent } from "../../net/log";
 import { phiRuntime } from "../../server-helpers/phi-runtime";
 import { getPhiRequestNavigationContext } from "../../server-helpers/request-runtime";
 import { readPhiPageReference } from "../../types/references";
-function collectNavigationLabels(items, labels = new Set()) {
+/**
+ * One label's identity for translation: its text and the language it is written in.
+ *
+ * The same English word is a different message when a Module shipped it than when an operator typed it
+ * on a Site whose source language is German, so the two are kept apart all the way to the answer.
+ */
+function navigationLabelKey(label) {
+    return `${label.sourceLocale ?? ""}\u0000${label.defaultMessage}`;
+}
+/** The labels to translate, grouped by source language; `""` is the Site's own. */
+function collectNavigationLabels(items, labels = new Map()) {
     for (const item of items) {
-        labels.add(item.label.defaultMessage);
+        const sourceLocale = item.label.sourceLocale ?? "";
+        const group = labels.get(sourceLocale) ?? new Set();
+        group.add(item.label.defaultMessage);
+        labels.set(sourceLocale, group);
         collectNavigationLabels(item.children, labels);
     }
     return labels;
@@ -22,7 +36,7 @@ function omitDeletedNavigationTargets(items, deletedIds) {
 function mapResolvedNavigationItem(item, translatedLabels) {
     return {
         key: item.id,
-        label: translatedLabels.get(item.label.defaultMessage) ?? item.label.defaultMessage,
+        label: translatedLabels.get(navigationLabelKey(item.label)) ?? item.label.defaultMessage,
         ...(readPhiCmsNavigationTargetPath(item.target) ? { href: readPhiCmsNavigationTargetPath(item.target) } : {}),
         ...(isPhiCmsNavigationOverlayTarget(item.target)
             ? {
@@ -49,11 +63,12 @@ export async function resolvePhiDescriptorNavigationItems(runtime, navKey, overl
     if (!normalizedNavKey.startsWith(`${runtime.area}:`)) {
         return null;
     }
-    const { catalog, activeModuleIds } = getPhiRequestNavigationContext(runtime.area);
+    const { catalog, activeModuleIds, routeTable } = getPhiRequestNavigationContext(runtime.area);
     const descriptorSurface = resolvePhiCmsActiveNavigationSurfaces({
         catalog,
         area: runtime.area,
         activeModuleIds,
+        routeTable,
         viewer: runtime.viewer,
     }).find((candidate) => candidate.navKey === normalizedNavKey);
     if (!descriptorSurface && !overlay) {
@@ -67,26 +82,26 @@ export async function resolvePhiDescriptorNavigationItems(runtime, navKey, overl
             const reference = readPhiPageReference(item.target.reference);
             if (!reference || reference.target.kind !== "module")
                 return item;
-            const route = resolvePhiCmsRouteDescriptorByPageId(catalog, reference.target.pageId);
             /*
-             * Whether the address exists, which is Module selection and nothing about this reader.
+             * Whether the address exists and where, which is the Area's active route table and nothing about
+             * this reader: the table holds only the routes that answer, on the address this Site gave them.
              *
-             * Checked against the Area the target named rather than the one this Navigation sits in. For a
-             * target in another Area the answer stops here: `activeModuleIds` is this Area's, and which
-             * Modules answer in another is a fact the request never read. Reading the route's path anyway
-             * would point a link at an address that is only served where that Module is switched on --
-             * exactly the guess `REFERENCES.md` forbids. A Site Page in another Area is a different matter
-             * and resolves normally; only a Module Page needs the activation nobody here has.
+             * Answered only for a target in this Area. For another Area the answer stops here: the table is
+             * this Area's, and which Modules answer in another is a fact the request never read. Reading the
+             * catalog's path anyway would point a link at an address that is only served where that Module is
+             * switched on -- exactly the guess `REFERENCES.md` forbids. A Site Page in another Area is a
+             * different matter and resolves normally; only a Module Page needs the activation nobody here has.
              */
             const targetArea = item.target.area ?? runtime.area;
-            const available = route != null && route.area === targetArea &&
-                targetArea === runtime.area && activeModuleIds.has(route.ownerModuleId);
+            const route = targetArea === runtime.area
+                ? resolvePhiCmsRoutePresetByPageId(routeTable, reference.target.pageId)?.descriptor ?? null
+                : null;
             return {
                 ...item,
                 target: {
                     ...item.target,
-                    resolvedPath: available ? route.path : null,
-                    deleted: !available,
+                    resolvedPath: route?.path ?? null,
+                    deleted: route == null,
                 },
             };
         }),
@@ -108,22 +123,41 @@ export async function resolvePhiDescriptorNavigationItems(runtime, navKey, overl
         });
     }
     const rt = phiRuntime(runtime);
-    const labels = [...collectNavigationLabels(surface.items)];
-    const translator = runtime.area === "builder"
-        ? createGlobalTranslator({
+    const translatedLabels = new Map();
+    /*
+     * One batch per source language. A Module's label names its language and is translated from it; an
+     * operator's names none and is read in the Site's source language, which the server supplies.
+     */
+    await Promise.all([...collectNavigationLabels(surface.items)].map(async ([sourceLocale, group]) => {
+        const labels = [...group];
+        const options = {
             apiBaseUrl: rt.apiBaseUrl,
             internalToken: rt.internalToken,
             locale: runtime.locale.current,
-        })
-        : createSiteTranslator({
-            apiBaseUrl: rt.apiBaseUrl,
-            internalToken: rt.internalToken,
-            siteKey: rt.siteKey,
-            locale: runtime.locale.current,
+            ...(sourceLocale ? { sourceLocale } : {}),
+        };
+        const translator = runtime.area === "builder"
+            ? createGlobalTranslator(options)
+            : createSiteTranslator({ ...options, siteKey: rt.siteKey });
+        /*
+         * A batch that fails leaves these labels in their source language for this render, and says so: the
+         * translation cache keeps nothing from a failed request (`gateway/tr.ts`), so the next render asks
+         * again. What must not happen is the quiet version, where a Site reads in the wrong language for a
+         * day and no log names the hour it started.
+         */
+        const translated = await translator.trBulk(labels, PHI_TR_CTX_WEB_UI_LABEL).catch((error) => {
+            logRuntimeEvent("warn", "navigation.labels.translation_failed", {
+                message: "Navigation labels could not be translated; the source texts are shown for this render.",
+                siteKey: rt.siteKey,
+                area: runtime.area,
+                error,
+                meta: { locale: runtime.locale.current, sourceLocale: sourceLocale ?? null, count: labels.length },
+            });
+            return labels;
+        });
+        labels.forEach((source, index) => {
+            translatedLabels.set(navigationLabelKey({ defaultMessage: source, ...(sourceLocale ? { sourceLocale } : {}) }), translated[index] ?? source);
         });
-    const translated = labels.length
-        ? await translator.trBulk(labels, PHI_TR_CTX_WEB_UI_LABEL).catch(() => labels)
-        : [];
-    const translatedLabels = new Map(labels.map((source, index) => [source, translated[index] ?? source]));
+    }));
     return surface.items.map((item) => mapResolvedNavigationItem(item, translatedLabels));
 }

package/components/widgets/server/navigation-request.d.ts

@@ -1,5 +1,4 @@
 import "server-only";
 import type { PhiBlockRuntime } from "../../../types";
 import type { PhiNavItem } from "../../shell/shell-types";
-export declare function resolvePhiNavigationRevisionFromRuntime(runtime: Pick<PhiBlockRuntime, "request">): number | null;
 export declare function resolvePhiNavigationItems(runtime: Pick<PhiBlockRuntime, "site" | "locale" | "area" | "viewer" | "request">, navKey: string): Promise<PhiNavItem[] | null>;

package/components/widgets/server/navigation-request.js

@@ -6,7 +6,7 @@ import { fetchSiteNavigationOverlay } from "../../../gateway/site-nav";
 import { phiRuntime } from "../../../server-helpers/phi-runtime";
 import { resolvePhiCmsReviewParams } from "../../../server-helpers/cms-review";
 import { resolvePhiDescriptorNavigationItems, } from "../navigation-descriptor-resolver.server";
-export function resolvePhiNavigationRevisionFromRuntime(runtime) {
+function resolvePhiNavigationRevisionFromRuntime(runtime) {
     const rawNavRevision = runtime.request?.searchParams?.navRevision?.trim();
     if (!rawNavRevision) {
         return null;

package/components/widgets/server/search.d.ts

@@ -1,6 +1,5 @@
 import type { PhiBlockRuntime } from "../../../types";
 import type { PhiCmsSearchWidgetConfig } from "../config/search-shared";
-import type { PhiSearchWidgetLabels } from "../label-types/search";
 export type PhiSearchWidgetServerProps = {
     runtime: Pick<PhiBlockRuntime, "locale">;
     config?: PhiCmsSearchWidgetConfig | null;
@@ -10,5 +9,4 @@ export type PhiSearchWidgetServerProps = {
     onQueryChange?: (query: string) => void;
     onQuerySubmit?: (query: string) => void;
 };
-export declare function loadPhiSearchWidgetLabels(runtime: Pick<PhiBlockRuntime, "locale">): Promise<PhiSearchWidgetLabels>;
 export declare function PhiSearchWidgetServer({ runtime, config, query, defaultQuery, disabled, onQueryChange, onQuerySubmit, }: PhiSearchWidgetServerProps): Promise<import("react").JSX.Element>;

package/components/widgets/server/search.js

@@ -3,7 +3,7 @@ import { getPhiSearchWidgetLabels } from "../label-sets/search";
 import { PhiRuntimeRenderClientType } from "../../../constants/runtime-render-client-types";
 import { PhiRuntimeModuleRenderClientHost } from "../../runtime/runtime-module-render-client-manifest";
 import { readPhiServerApiCredentials } from "../../../helpers/phis-server-credentials";
-export async function loadPhiSearchWidgetLabels(runtime) {
+async function loadPhiSearchWidgetLabels(runtime) {
     return getPhiSearchWidgetLabels({
         apiBaseUrl: readPhiServerApiCredentials().apiBaseUrl,
         internalToken: readPhiServerApiCredentials().internalToken,

package/components/widgets/shared/bullet-list-vocabulary.d.ts

@@ -0,0 +1,80 @@
+import type { PhiCmsConfigField } from "../../../types/cms-plugins";
+import { type PhiSurface } from "../../../types/surface";
+import { type PhiSpacingScaleKey } from "../config/spacing-options";
+/**
+ * What stands before an entry. `number` counts the entries of its level from 1 (or a Markdown list's
+ * own start); `icon` draws the list's one icon; `none` draws nothing and keeps the indent.
+ */
+export declare const PHI_BULLET_LIST_MARKERS: readonly ["dot", "circle", "dash", "number", "icon", "none"];
+export type PhiBulletListMarker = (typeof PHI_BULLET_LIST_MARKERS)[number];
+/**
+ * How deep a list goes. Each level has a marker of its own; an entry written deeper stands at the
+ * deepest, and a Markdown list nested deeper takes the deepest level's marker.
+ */
+export declare const PHI_BULLET_LIST_LEVELS: readonly [1, 2, 3];
+export type PhiBulletListLevel = (typeof PHI_BULLET_LIST_LEVELS)[number];
+export declare const PhiBulletListFlag: {
+    /** A line between entries, for entries without a ground of their own. */
+    readonly Dividers: number;
+};
+/**
+ * How a list is set. Absent parts take the defaults below.
+ *
+ * `itemSurface` is each entry's own box, from the Surface vocabulary -- a card, a wash, or nothing. A
+ * box around the whole list is the Widget's Surface, not this. An entry's Surface has no `tone`: a mode
+ * of its own is a theme scope per entry, which is a page's worth of providers for a list.
+ */
+export type PhiBulletListStyle = {
+    level1?: PhiBulletListMarker;
+    level2?: PhiBulletListMarker;
+    level3?: PhiBulletListMarker;
+    /** An icon name, as the icon picker writes it; drawn by every level whose marker is `icon`. */
+    icon?: string;
+    itemSurface?: PhiSurface | null;
+    gap?: PhiSpacingScaleKey;
+    flags?: number;
+};
+export type PhiResolvedBulletListStyle = {
+    markers: Record<PhiBulletListLevel, PhiBulletListMarker>;
+    icon: string | null;
+    itemSurface: PhiSurface | null;
+    gap: PhiSpacingScaleKey;
+    flags: number;
+};
+/** A stored list style, part by part; whatever is not one of its values is left out. */
+export declare function readPhiBulletListStyle(value: unknown): PhiBulletListStyle | undefined;
+export declare function resolvePhiBulletListStyle(style: PhiBulletListStyle | null | undefined): PhiResolvedBulletListStyle;
+/** The level an entry at `depth` (1 for the outermost) is drawn at. */
+export declare function resolvePhiBulletListLevel(depth: number): PhiBulletListLevel;
+/**
+ * One entry of a list written as a list: its text, how deep it stands, and the values its text names.
+ *
+ * `values` keep what changes from Site to Site out of the sentence: "Site key: %1" with the key beside it
+ * is translated once and filled after, where "Site key: acme" would be a sentence of its own for every
+ * Site and never found in a catalogue. The values themselves are never translated.
+ */
+export type PhiBulletListEntry = {
+    text: string;
+    /** 1 for the outermost level, which is what an entry without one stands at. */
+    level?: number;
+    values?: string[];
+};
+export declare function readPhiBulletListEntries(value: unknown): PhiBulletListEntry[];
+/** An entry of the tree the Control draws: what it shows, and the entries one level below it. */
+export type PhiBulletListNode<Content> = {
+    content: Content;
+    children?: PhiBulletListNode<Content>[];
+};
+/**
+ * A list written flat, with levels, as the tree it reads as. An entry deeper than the one before it by
+ * more than a level hangs one level below it all the same: a level cannot be skipped in a nested list,
+ * and an entry that tried stays with the entry it follows rather than jumping.
+ */
+export declare function buildPhiBulletListTree<Entry extends {
+    level?: number;
+}, Content>(entries: readonly Entry[], content: (entry: Entry, index: number) => Content): PhiBulletListNode<Content>[];
+/**
+ * The Inspector fields for a list style stored under `key`, under a divider titled `heading`. Every Widget
+ * with a list offers these, so a list is set the same way wherever it stands.
+ */
+export declare function buildPhiBulletListFields(key: string, heading: string): PhiCmsConfigField[];

package/components/widgets/shared/bullet-list-vocabulary.js

@@ -0,0 +1,159 @@
+import { isPhiRecord } from "../../../helpers/is-record";
+import { readPhiSurface } from "../../../types/surface";
+import { PHI_SPACING_SCALE_KEYS } from "../config/spacing-options";
+/*
+ * A list's words, apart from the Control that draws it: Widget definitions read them on the server, and
+ * each Widget that has a list -- the Description's aside, the Markdown text's lists -- stores the same
+ * style under a key of its own and offers the same fields for it.
+ */
+/**
+ * What stands before an entry. `number` counts the entries of its level from 1 (or a Markdown list's
+ * own start); `icon` draws the list's one icon; `none` draws nothing and keeps the indent.
+ */
+export const PHI_BULLET_LIST_MARKERS = ["dot", "circle", "dash", "number", "icon", "none"];
+/**
+ * How deep a list goes. Each level has a marker of its own; an entry written deeper stands at the
+ * deepest, and a Markdown list nested deeper takes the deepest level's marker.
+ */
+export const PHI_BULLET_LIST_LEVELS = [1, 2, 3];
+export const PhiBulletListFlag = {
+    /** A line between entries, for entries without a ground of their own. */
+    Dividers: 1 << 0,
+};
+/** The markers a browser cycles through, and a tight gap. */
+const PHI_BULLET_LIST_DEFAULT_STYLE = {
+    level1: "dot",
+    level2: "circle",
+    level3: "dash",
+    gap: "xs",
+};
+function readMarker(value) {
+    return PHI_BULLET_LIST_MARKERS.includes(value) ? value : undefined;
+}
+/** A stored list style, part by part; whatever is not one of its values is left out. */
+export function readPhiBulletListStyle(value) {
+    if (!isPhiRecord(value)) {
+        return undefined;
+    }
+    const record = value;
+    const { tone: _tone, ...itemSurface } = readPhiSurface(record.itemSurface) ?? {};
+    void _tone;
+    const style = {
+        level1: readMarker(record.level1),
+        level2: readMarker(record.level2),
+        level3: readMarker(record.level3),
+        icon: typeof record.icon === "string" && record.icon.trim() ? record.icon : undefined,
+        // `null` is a list whose entries were set to have no box, which a default must not draw again.
+        itemSurface: Object.keys(itemSurface).length > 0 ? itemSurface : record.itemSurface === null ? null : undefined,
+        gap: PHI_SPACING_SCALE_KEYS.includes(record.gap) ? record.gap : undefined,
+        flags: typeof record.flags === "number" && Number.isInteger(record.flags) ? record.flags : undefined,
+    };
+    const stated = Object.fromEntries(Object.entries(style).filter(([, part]) => part !== undefined));
+    return Object.keys(stated).length > 0 ? stated : undefined;
+}
+export function resolvePhiBulletListStyle(style) {
+    return {
+        markers: {
+            1: style?.level1 ?? PHI_BULLET_LIST_DEFAULT_STYLE.level1,
+            2: style?.level2 ?? PHI_BULLET_LIST_DEFAULT_STYLE.level2,
+            3: style?.level3 ?? PHI_BULLET_LIST_DEFAULT_STYLE.level3,
+        },
+        icon: style?.icon ?? null,
+        itemSurface: style?.itemSurface ?? null,
+        gap: style?.gap ?? PHI_BULLET_LIST_DEFAULT_STYLE.gap,
+        flags: style?.flags ?? 0,
+    };
+}
+/** The level an entry at `depth` (1 for the outermost) is drawn at. */
+export function resolvePhiBulletListLevel(depth) {
+    const deepest = PHI_BULLET_LIST_LEVELS[PHI_BULLET_LIST_LEVELS.length - 1];
+    return Math.min(Math.max(1, Math.trunc(depth) || 1), deepest);
+}
+export function readPhiBulletListEntries(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((entry) => {
+        if (!isPhiRecord(entry) || typeof entry.text !== "string") {
+            return [];
+        }
+        const record = entry;
+        const level = typeof record.level === "number" ? resolvePhiBulletListLevel(record.level) : 1;
+        const values = Array.isArray(record.values)
+            ? record.values.map((item) => (typeof item === "string" || typeof item === "number" ? String(item) : ""))
+            : [];
+        return [{
+                text: record.text,
+                ...(level > 1 ? { level } : {}),
+                ...(values.length > 0 ? { values } : {}),
+            }];
+    });
+}
+/**
+ * A list written flat, with levels, as the tree it reads as. An entry deeper than the one before it by
+ * more than a level hangs one level below it all the same: a level cannot be skipped in a nested list,
+ * and an entry that tried stays with the entry it follows rather than jumping.
+ */
+export function buildPhiBulletListTree(entries, content) {
+    const root = [];
+    const open = [root];
+    entries.forEach((entry, index) => {
+        const wanted = resolvePhiBulletListLevel(entry.level ?? 1);
+        const level = Math.min(wanted, open.length);
+        open.length = level;
+        const node = { content: content(entry, index) };
+        open[level - 1].push(node);
+        node.children = [];
+        open.push(node.children);
+    });
+    const prune = (nodes) => {
+        for (const node of nodes) {
+            if (node.children?.length) {
+                prune(node.children);
+            }
+            else {
+                delete node.children;
+            }
+        }
+    };
+    prune(root);
+    return root;
+}
+const PHI_BULLET_LIST_MARKER_LABELS = {
+    dot: "Dot",
+    circle: "Circle",
+    dash: "Dash",
+    number: "Number",
+    icon: "Icon",
+    none: "None",
+};
+/**
+ * The Inspector fields for a list style stored under `key`, under a divider titled `heading`. Every Widget
+ * with a list offers these, so a list is set the same way wherever it stands.
+ */
+export function buildPhiBulletListFields(key, heading) {
+    const markerOptions = PHI_BULLET_LIST_MARKERS.map((marker) => ({ value: marker, label: PHI_BULLET_LIST_MARKER_LABELS[marker] }));
+    return [
+        ...PHI_BULLET_LIST_LEVELS.map((level, index) => ({
+            key: `${key}.level${level}`,
+            type: "choice",
+            label: `Level ${level}`,
+            options: markerOptions,
+            ...(index === 0 ? { heading } : {}),
+        })),
+        { key: `${key}.icon`, type: "icon", label: "Icon" },
+        {
+            key: `${key}.gap`,
+            type: "choice",
+            label: "Gap",
+            options: PHI_SPACING_SCALE_KEYS.map((gap) => ({ value: gap, label: gap })),
+        },
+        {
+            key: `${key}.flags`,
+            type: "flags",
+            label: "Lines",
+            options: [{ value: PhiBulletListFlag.Dividers, label: "Dividers between entries" }],
+        },
+        { key: `${key}.itemSurface`, type: "surface", label: "Entries", tone: false },
+    ];
+}