@phis/ui 0.4.0 → 0.4.2

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

@@ -122,6 +122,11 @@ export type PhiTableControlProps<TRow extends Record<string, unknown>> = {
     bordered?: boolean;
     striped?: boolean;
     showHeader?: boolean;
+    /**
+     * The header row stays at the top while the rows scroll under it: under the Shell's Header on a page,
+     * at the top edge of a Modal's or Drawer's body. `styles/controls.css` places it.
+     */
+    stickyHeader?: boolean;
     footer?: PhiTableControlFooter;
     summary?: PhiTableControlSummary;
     size?: PhiControlSize;
@@ -141,4 +146,4 @@ export type PhiTableControlProps<TRow extends Record<string, unknown>> = {
     onExternalDrop?: (event: DragEvent<HTMLDivElement>) => void;
 };
 export declare function readPhiTableControlValue(row: Record<string, unknown>, path: string): unknown;
-export declare function PhiTableControl<TRow extends Record<string, unknown>>({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering, onColumnOrderChange, rowSelection, pagination, tree, rowReordering, editing, loading, bordered, striped, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }: PhiTableControlProps<TRow>): import("react").JSX.Element;
+export declare function PhiTableControl<TRow extends Record<string, unknown>>({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering, onColumnOrderChange, rowSelection, pagination, tree, rowReordering, editing, loading, bordered, striped, stickyHeader, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }: PhiTableControlProps<TRow>): import("react").JSX.Element;

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

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePhiShellStickyTop } from "../shell/use-phi-shell-sticky-top";
 import { Button, Flex, Table } from "antd";
 import { DndContext, KeyboardSensor, PointerSensor, closestCenter, useSensor, useSensors, } from "@dnd-kit/core";
 import { SortableContext, sortableKeyboardCoordinates, useSortable, } from "@dnd-kit/sortable";
@@ -354,7 +355,7 @@ function buildRowMove(rows, rowIdentityPath, parentRowIdentityPath, movedRowIden
         afterRowIdentity: placement === "after" ? targetRowIdentity : null,
     };
 }
-export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering = false, onColumnOrderChange, rowSelection, pagination = false, tree, rowReordering, editing, loading = false, bordered, striped = false, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }) {
+export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, sortingMode, sorts, onSortsChange, columnReordering = false, onColumnOrderChange, rowSelection, pagination = false, tree, rowReordering, editing, loading = false, bordered, striped = false, stickyHeader = false, showHeader, footer, summary, size, emptyText, layout, rowStyle, onRowActivate, onExternalRowDragOver, onExternalRowDrop, onExternalDragOver, onExternalDrop, }) {
     const { token } = usePhiConfig();
     const [editingRowIdentityState, setEditingRowIdentity] = useState(null);
     const [rowEditPatch, setRowEditPatch] = useState({});
@@ -988,6 +989,8 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
     const hasClosingBlock = !loading &&
         (Boolean(footer) || (summary != null && summary.placement !== "sticky-top"));
     const frameRef = useRef(null);
+    // Where the Shell's Header ends, which is where a sticky header row stops (`styles/controls.css`).
+    usePhiShellStickyTop({ active: stickyHeader && showHeader !== false, elementRef: frameRef });
     const [headerBox, setHeaderBox] = useState(null);
     useEffect(() => {
         const frame = frameRef.current;
@@ -1007,11 +1010,15 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
         observer.observe(frame);
         return () => observer.disconnect();
     }, [showHeader, loading]);
-    const table = (_jsx(Table, { className: ["phi-table-control", hasClosingBlock ? "phi-table-control--closing-block" : null]
+    const table = (_jsx(Table, { className: [
+            "phi-table-control",
+            hasClosingBlock ? "phi-table-control--closing-block" : null,
+            stickyHeader && showHeader !== false ? "phi-table-control--sticky-header" : null,
+        ]
             .filter(Boolean)
             .join(" "), style: { "--phi-table-striped-row-background": token.colorFillAlter }, rowKey: (row) => loading
             ? `__phi_table_loading_${String(row[PHI_TABLE_LOADING_ROW])}`
-            : String(readIdentity(row, rowIdentityPath)), columns: renderedColumns, dataSource: loading ? loadingRows : dataSource, bordered: bordered, showHeader: showHeader, tableLayout: layout.mode, size: size, rowClassName: (_row, index) => striped && index % 2 === 1 ? "phi-table-control__row--striped" : "", rowSelection: loading ? undefined : antdRowSelection, components: rowReordering?.enabled && !loading ? { body: { row: PhiTableSortableRow } } : undefined, scroll: layout.overflowX === "auto" ? { x: true } : undefined, pagination: pagination === false ? false : {
+            : String(readIdentity(row, rowIdentityPath)), columns: renderedColumns, dataSource: loading ? loadingRows : dataSource, bordered: bordered, showHeader: showHeader, tableLayout: layout.mode, size: size, rowClassName: (_row, index) => striped && index % 2 === 1 ? "phi-table-control__row--striped" : "", rowSelection: loading ? undefined : antdRowSelection, components: rowReordering?.enabled && !loading ? { body: { row: PhiTableSortableRow } } : undefined, scroll: layout.overflowX === "auto" ? { x: true } : undefined, sticky: stickyHeader && showHeader !== false ? true : undefined, pagination: pagination === false ? false : {
             ...{ [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "pagination" },
             current: pagination.page,
             pageSize: pagination.pageSize,
@@ -1097,7 +1104,12 @@ export function PhiTableControl({ rows, rowIdentityPath, columns, columnOrder, s
                     insertionGapIndex,
                     insertionGapHeight: activeDragRowHeight,
                 }, children: table }) }) })) : table;
-    const constrainedTable = (_jsxs("div", { ref: frameRef, style: { position: "relative", width: "100%", maxWidth: "100%", minWidth: 0, overflow: "hidden" }, children: [renderedTable, headerBox ? (_jsx("div", { "aria-hidden": true, [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "header", style: { position: "absolute", left: 0, right: 0, top: headerBox.top, height: headerBox.height, pointerEvents: "none" } })) : null] }));
+    /*
+     * Clipped, not hidden: `hidden` makes the frame a scroll container, and a sticky header row then sticks
+     * to the frame's own top -- pushed down inside the Table by the Shell's Header height -- instead of to
+     * the page. `clip` cuts off the same overflow and leaves the page the one that scrolls.
+     */
+    const constrainedTable = (_jsxs("div", { ref: frameRef, style: { position: "relative", width: "100%", maxWidth: "100%", minWidth: 0, overflow: "clip" }, children: [renderedTable, headerBox ? (_jsx("div", { "aria-hidden": true, [PHI_VISUAL_ANCHOR_PART_ATTRIBUTE]: "header", style: { position: "absolute", left: 0, right: 0, top: headerBox.top, height: headerBox.height, pointerEvents: "none" } })) : null] }));
     return onExternalDragOver || onExternalDrop ? (_jsx("div", { onDragOver: (event) => {
             if (event.defaultPrevented) {
                 setExternalAppendActive(false);

package/components/layouts/layout-definitions.d.ts

@@ -483,7 +483,7 @@ export declare const PHI_GRID_LAYOUT_DEFINITION: {
     kind: "layout";
     pluginKey: string;
     typeKey: string;
-    slotSizePolicy: "fill";
+    slotSizePolicy: "fill-inline";
     title: string;
     description: string;
     category: "structure";
@@ -1176,7 +1176,7 @@ export declare const PHI_CORE_LAYOUT_DEFINITIONS: readonly [{
     kind: "layout";
     pluginKey: string;
     typeKey: string;
-    slotSizePolicy: "fill";
+    slotSizePolicy: "fill-inline";
     title: string;
     description: string;
     category: "structure";

package/components/layouts/layout-definitions.js

@@ -415,7 +415,12 @@ export const PHI_GRID_LAYOUT_DEFINITION = {
     kind: "layout",
     pluginKey: resolvePhiCmsLayoutPluginKey("grid"),
     typeKey: "grid",
-    slotSizePolicy: "fill",
+    /*
+     * As wide as its slot, as tall as its rows. A Grid is content in flow: filling the block axis as well
+     * let a vertical stack share its height out among the Grids in it, and each one, held to its share,
+     * spilled its rows over the next section.
+     */
+    slotSizePolicy: "fill-inline",
     title: "Grid",
     description: "Slots in rows, as many to a row as the Grid's own width allows.",
     category: "structure",

package/components/shell/use-phi-shell-sticky-top.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from "react";
+export declare function usePhiShellStickyTop({ active, elementRef, }: {
+    active: boolean;
+    elementRef: RefObject<HTMLElement | null>;
+}): void;

package/components/shell/use-phi-shell-sticky-top.js

@@ -0,0 +1,78 @@
+"use client";
+import { useEffect } from "react";
+/**
+ * How far down the viewport the Shell's Header holds right now, published on the Shell.
+ *
+ * Something that sticks to the top of the page -- a Table's header row -- has to stick under the Header
+ * rather than behind it, and where the Header ends is not a constant: each band sticks or scrolls by its
+ * own config, and a revealing `header_top` slides away while the visitor reads down and comes back when
+ * they scroll up. So the edge is measured, not configured: the lowest bottom of every Header band that is
+ * stuck at this moment, written as `--phi-shell-sticky-top` on the Shell element. Unset, a reader falls
+ * back to `0px`, which is right for a Shell without a sticky Header.
+ *
+ * Run by whatever sticks under it -- every sticky Table does -- so a page without one loads nothing for
+ * it. Each runner measures all the bands and they all write the same value. Not inside an Overlay: a
+ * Modal's or Drawer's body scrolls on its own, and its top edge is the line.
+ */
+const PHI_SHELL_STICKY_TOP_PROPERTY = "--phi-shell-sticky-top";
+const HEADER_BANDS = '[data-phi-region-key^="header_"]:not([hidden])';
+function measurePhiShellStickyTop(shell) {
+    let bottom = 0;
+    for (const band of shell.querySelectorAll(HEADER_BANDS)) {
+        const style = window.getComputedStyle(band);
+        if (style.position !== "sticky" && style.position !== "fixed") {
+            continue;
+        }
+        const rect = band.getBoundingClientRect();
+        const stuckAt = Number.parseFloat(style.top) || 0;
+        // Below its sticking line it is still in flow; above the viewport it has slid away.
+        if (rect.height === 0 || rect.top > stuckAt + 1 || rect.bottom <= 0) {
+            continue;
+        }
+        bottom = Math.max(bottom, rect.bottom);
+    }
+    return `${Math.round(bottom)}px`;
+}
+const OVERLAY_BODIES = "[data-phi-modal-body-content], [data-phi-drawer-body-content]";
+export function usePhiShellStickyTop({ active, elementRef, }) {
+    useEffect(() => {
+        const element = elementRef.current;
+        const shell = active && element && !element.closest(OVERLAY_BODIES)
+            ? element.closest("[data-phi-shell-layout]")
+            : null;
+        if (!element || !shell) {
+            return undefined;
+        }
+        let frame = 0;
+        const publish = () => {
+            frame = 0;
+            const next = measurePhiShellStickyTop(shell);
+            if (shell.style.getPropertyValue(PHI_SHELL_STICKY_TOP_PROPERTY) !== next) {
+                shell.style.setProperty(PHI_SHELL_STICKY_TOP_PROPERTY, next);
+            }
+        };
+        const schedule = () => {
+            if (frame === 0) {
+                frame = window.requestAnimationFrame(publish);
+            }
+        };
+        publish();
+        window.addEventListener("scroll", schedule, { passive: true });
+        window.addEventListener("resize", schedule);
+        // A revealing band moves by a transition; its end is where it settled.
+        shell.addEventListener("transitionend", schedule);
+        const observer = new ResizeObserver(schedule);
+        for (const band of shell.querySelectorAll(HEADER_BANDS)) {
+            observer.observe(band);
+        }
+        return () => {
+            if (frame !== 0) {
+                window.cancelAnimationFrame(frame);
+            }
+            window.removeEventListener("scroll", schedule);
+            window.removeEventListener("resize", schedule);
+            shell.removeEventListener("transitionend", schedule);
+            observer.disconnect();
+        };
+    }, [active, elementRef]);
+}

package/components/widgets/helpers/semantic-html-translation.d.ts

@@ -1,2 +1,4 @@
 import "server-only";
-export declare function translateSemanticHtml(sourceHtml: string, sourceLocale?: string): Promise<string>;
+export declare function translateSemanticHtml(sourceHtml: string, sourceLocale?: string, 
+/** The render's locale. Without it the request's is asked, and a static render has no request. */
+locale?: string): Promise<string>;

package/components/widgets/helpers/semantic-html-translation.js

@@ -1,7 +1,7 @@
 import "server-only";
 import renderHtml from "dom-serializer";
 import { parseDocument } from "htmlparser2";
-import { trBulk } from "../../../server-helpers/translate";
+import { trBulk, trBulkForLocale } from "../../../server-helpers/translate";
 import { sanitizePhiHtmlWidgetMarkup } from "./html-content";
 const SEMANTIC_HTML_BLOCKS = new Set([
     "p",
@@ -49,7 +49,9 @@ function renderNodes(nodes) {
 function hasVisibleText(html) {
     return html.replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").trim().length > 0;
 }
-export async function translateSemanticHtml(sourceHtml, sourceLocale) {
+export async function translateSemanticHtml(sourceHtml, sourceLocale, 
+/** The render's locale. Without it the request's is asked, and a static render has no request. */
+locale) {
     const sanitized = sanitizePhiHtmlWidgetMarkup(sourceHtml);
     if (!sanitized) {
         return "";
@@ -64,7 +66,10 @@ export async function translateSemanticHtml(sourceHtml, sourceLocale) {
     if (units.length === 0) {
         return sanitized;
     }
-    const translated = await trBulk(units.map((unit) => unit.html), 0, "html", sourceLocale);
+    const msgs = units.map((unit) => unit.html);
+    const translated = locale
+        ? await trBulkForLocale(locale, msgs, 0, "html", sourceLocale)
+        : await trBulk(msgs, 0, "html", sourceLocale);
     units.forEach((unit, index) => {
         const fragment = parseDocument(translated[index] ?? unit.html);
         unit.node.children = fragment.children ?? [];

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

@@ -127,6 +127,11 @@ export async function resolvePhiDescriptorNavigationItems(runtime, navKey, overl
     /*
      * 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.
+     *
+     * The batch also decides the store. A Module's label is the platform's text, the same on every Site,
+     * so it is translated once in the global store, which only the operator edits. A Site that wants
+     * other words renames the entry, the label loses its `sourceLocale`, and from then on it is the
+     * Site's own text in the Site's store. The Builder's surfaces carry Module labels only.
      */
     await Promise.all([...collectNavigationLabels(surface.items)].map(async ([sourceLocale, group]) => {
         const labels = [...group];
@@ -136,7 +141,7 @@ export async function resolvePhiDescriptorNavigationItems(runtime, navKey, overl
             locale: runtime.locale.current,
             ...(sourceLocale ? { sourceLocale } : {}),
         };
-        const translator = runtime.area === "builder"
+        const translator = sourceLocale || runtime.area === "builder"
             ? createGlobalTranslator(options)
             : createSiteTranslator({ ...options, siteKey: rt.siteKey });
         /*

package/components/widgets/shared/markdown-body-client.d.ts

@@ -1,6 +1,6 @@
 import type { PhiClientBlockBaseProps, PhiNoLabels } from "../../../types";
 import type { PhiCodeToken } from "./markdown-code-tokens";
-import type { PhiMarkdownTextAlign } from "../../../types/core-widget-placements";
+import type { PhiMarkdownImageFloat, PhiMarkdownTextAlign } from "../../../types/core-widget-placements";
 import { type PhiSpacingScaleKey } from "../config/spacing-options";
 import type { PhiMarkdownTocHeading } from "../../../types/markdown";
 import { type PhiBulletListStyle } from "./bullet-list-vocabulary";
@@ -75,6 +75,7 @@ export type PhiMarkdownWidgetClientProps = PhiClientBlockBaseProps<PhiNoLabels,
     tocKey?: string;
     headings?: PhiMarkdownTocHeading[];
     textAlign?: PhiMarkdownTextAlign;
+    imageFloat?: PhiMarkdownImageFloat;
     textBlockSpacingBefore?: PhiSpacingScaleKey;
     textBlockSpacingAfter?: PhiSpacingScaleKey;
     headingBlockSpacingBefore?: PhiSpacingScaleKey;

package/components/widgets/shared/markdown-body-client.js

@@ -162,7 +162,9 @@ export function PhiMarkdownWidgetClient({ config }) {
         marginBlockStart: resolvePhiSpacingScaleValue(config?.headingBlockSpacingBefore ?? "none"),
         marginBlockEnd: resolvePhiSpacingScaleValue(config?.headingBlockSpacingAfter ?? "sm"),
     };
-    return (_jsx("div", { style: { display: "grid", gap: 0, width: "100%", textAlign: config?.textAlign }, children: renderBlocks(blocks, token, paragraphBlockStyle, headingBlockStyle, {
+    return (_jsx("div", { className: config?.imageFloat ? `phi-markdown-body phi-markdown-body--float-${config.imageFloat}` : undefined, style: config?.imageFloat
+            ? { display: "flow-root", width: "100%", textAlign: config.textAlign, containerType: "inline-size" }
+            : { display: "grid", gap: 0, width: "100%", textAlign: config?.textAlign }, children: renderBlocks(blocks, token, paragraphBlockStyle, headingBlockStyle, {
             style: resolvePhiBulletListStyle(config?.list),
             depth: 1,
         }) }));

package/components/widgets/shared/markdown-render.js

@@ -2,7 +2,7 @@ import { cache } from "react";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
-import { trBulk } from "../../../server-helpers/translate";
+import { trBulk, trBulkForLocale } from "../../../server-helpers/translate";
 import { resolvePhiCodeLanguage, tokenizePhiCode } from "./markdown-code-tokens";
 import { readPhiInternalReference } from "../../../types/references";
 import { resolvePhiWidgetInternalReferences } from "../helpers/internal-reference-resolver.server";
@@ -56,6 +56,13 @@ function normalizePotentialPhiScheme(value) {
  * accepted let `javascript:` and `data:` through here while the inline path refused them.
  */
 const PHI_EXTERNAL_DOCUMENT_URL_SCHEMES = /^(?:https?:|mailto:|tel:)$/iu;
+/*
+ * A picture written into the text itself may also be a data URL of an image type -- the one way a Module
+ * brings a drawing with its copy, since it cannot put a file into the Site's `public/`. An `<img>` runs
+ * nothing it loads, an SVG's scripts included, so the type list is what keeps this a picture. Links
+ * stay on the scheme list above, and a fetched document gets no data URLs at all.
+ */
+const PHI_INLINE_IMAGE_DATA_URL = /^data:image\/(?:png|jpeg|gif|webp|svg\+xml)[;,]/iu;
 function resolveExternalDocumentUrl(value, sourceUrl) {
     const normalized = value.trim();
     if (!normalized || normalizePotentialPhiScheme(normalized).startsWith("phis:"))
@@ -119,7 +126,7 @@ async function projectInternalMarkdownNodes(tree, runtime) {
                 const src = resolved.assetUrls.get(reference.assetId);
                 return src ? [{ ...node, url: src, children }] : [];
             }
-            if (!/^https?:/iu.test(node.url ?? ""))
+            if (!/^https?:/iu.test(node.url ?? "") && !PHI_INLINE_IMAGE_DATA_URL.test(node.url ?? ""))
                 return [];
             return [{ ...node, children }];
         }
@@ -294,11 +301,21 @@ function parseTranslatedMarkdownInlines(translatedHtml, metadata) {
     appendText(translatedHtml.slice(cursor));
     return stack.length === 1 ? stack[0]?.children ?? [] : null;
 }
-async function buildMarkdownInlineMap(tree, translate, sourceLocale) {
+/*
+ * The render's own locale where there is one. A static render has no request to ask: `trBulk` reads the
+ * locale from the request headers, finds none, and answers in the Site's default -- which left every
+ * static Public page's body in its source language under a translated header.
+ */
+function translateUnits(locale, msgs, format, sourceLocale) {
+    return locale
+        ? trBulkForLocale(locale, msgs, 0, format, sourceLocale)
+        : trBulk(msgs, 0, format, sourceLocale);
+}
+async function buildMarkdownInlineMap(tree, translate, sourceLocale, locale) {
     const units = [];
     collectMarkdownTranslationUnits(tree, units);
     const translated = translate && units.length > 0
-        ? await trBulk(units.map((unit) => unit.html), 0, "html", sourceLocale)
+        ? await translateUnits(locale, units.map((unit) => unit.html), "html", sourceLocale)
         : units.map((unit) => unit.html);
     /*
      * Image titles are prose and translate as plain text, each on its own: they are separate sentences
@@ -307,7 +324,7 @@ async function buildMarkdownInlineMap(tree, translate, sourceLocale) {
      */
     const titleSlots = units.flatMap((unit) => unit.metadata.titles.flatMap((title, index) => title ? [{ metadata: unit.metadata, index, title }] : []));
     if (translate && titleSlots.length > 0) {
-        const translatedTitles = await trBulk(titleSlots.map((slot) => slot.title), 0, "text", sourceLocale);
+        const translatedTitles = await translateUnits(locale, titleSlots.map((slot) => slot.title), "text", sourceLocale);
         titleSlots.forEach((slot, index) => {
             slot.metadata.titles[slot.index] = translatedTitles[index] || slot.title;
         });
@@ -508,7 +525,7 @@ async function resolveMarkdownRenderDataFromSource(markdown, translate, headingI
         headingIdPrefix,
         headingOffset,
     };
-    const inlineMap = await buildMarkdownInlineMap(tree, translate, sourceLocale);
+    const inlineMap = await buildMarkdownInlineMap(tree, translate, sourceLocale, runtime?.locale.current);
     const blocks = mapBlockNodes(tree.children, context, inlineMap);
     return { blocks, headings: context.headings };
 }

package/helpers/text-source.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Whose words a text Widget holds, which decides the store that translates them.
+ *
+ * A Preset's text is the platform's: the same sentence on every installation, translated once in the
+ * global store, which only the operator edits. Text an author wrote on a Site is the Site's and goes to
+ * the Site's store. The Preset says so by writing `textSource: "preset"` beside its words; the Builder
+ * drops the marker the moment an author changes one of the Widget's texts, and from then on all of them
+ * are the Site's.
+ *
+ * A marker rather than a translation done by the Preset itself: adopting a Preset stores the tree it
+ * built, so a Preset that translated its words would freeze one locale into the Site's copy.
+ */
+export declare const PHI_TEXT_SOURCE_PRESET: "preset";
+export type PhiTextSource = typeof PHI_TEXT_SOURCE_PRESET;
+export declare function readPhiTextSource(value: unknown): PhiTextSource | undefined;
+/** Whether a Builder edit of this field ends the Preset's ownership of the Widget's words. */
+export declare function isPhiAuthoredTextField(field: {
+    type?: string;
+}): boolean;

package/helpers/text-source.js

@@ -0,0 +1,20 @@
+/**
+ * Whose words a text Widget holds, which decides the store that translates them.
+ *
+ * A Preset's text is the platform's: the same sentence on every installation, translated once in the
+ * global store, which only the operator edits. Text an author wrote on a Site is the Site's and goes to
+ * the Site's store. The Preset says so by writing `textSource: "preset"` beside its words; the Builder
+ * drops the marker the moment an author changes one of the Widget's texts, and from then on all of them
+ * are the Site's.
+ *
+ * A marker rather than a translation done by the Preset itself: adopting a Preset stores the tree it
+ * built, so a Preset that translated its words would freeze one locale into the Site's copy.
+ */
+export const PHI_TEXT_SOURCE_PRESET = "preset";
+export function readPhiTextSource(value) {
+    return value === PHI_TEXT_SOURCE_PRESET ? value : undefined;
+}
+/** Whether a Builder edit of this field ends the Preset's ownership of the Widget's words. */
+export function isPhiAuthoredTextField(field) {
+    return field.type === "string";
+}

package/next/config.mjs

@@ -57,7 +57,7 @@ function customRenders(antd, h, Fragment) {
     Form: (Form) => h(Form, null, h(Form.Item, { label: "Label" }, h(antd.Input))),
     Dropdown: (Dropdown) => h(Dropdown, { menu: { items: [] } }, h("div")),
     Menu: (Menu) => h(Menu, { items: [] }),
-    QRCode: (QRCode) => h(QRCode, { value: "https://phisys.com" }),
+    QRCode: (QRCode) => h(QRCode, { value: "https://phis.dev" }),
     Tree: (Tree) => h(Tree, { treeData: [] }),
     Tag: (Tag) => h(Fragment, null, h(Tag, { color: "blue" }, "Tag"), h(Tag, { color: "success" }, "Tag")),
     Badge: (Badge) => h(Fragment, null, h(Badge), h(Badge.Ribbon)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phis/ui",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/plugins/runtime-modules/auth/trees/phi-default-pub-confirm-page-tree.js

@@ -1,3 +1,4 @@
+import { PHI_TEXT_SOURCE_PRESET } from "../../../../helpers/text-source";
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
 import { PHI_SPACE } from "../../../../theme/antd-css-var-contract";
 import { PHI_AUTH_RUNTIME_MODULE_ID } from "../ids";
@@ -97,6 +98,7 @@ export async function buildPhiDefaultPubConfirmPageTree({ page, presetKey, }) {
                 sortOrder: 0,
                 label: "pub confirmation description widget",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     eyebrow: "Confirm Email",
                     title: "Activate your account",
                     description: "Review your registration details and confirm your email address to activate access.",
@@ -160,6 +162,7 @@ export async function buildPhiDefaultPubConfirmPageTree({ page, presetKey, }) {
                 slotIndex: 2,
                 label: "pub confirmation missing token",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     text: "No confirmation token was provided. Open the confirmation link from your email.",
                     tone: "secondary",
                     visibleWhen: withoutToken,

package/plugins/runtime-modules/auth/trees/phi-default-pub-login-page-tree.js

@@ -1,3 +1,4 @@
+import { PHI_TEXT_SOURCE_PRESET } from "../../../../helpers/text-source";
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
 import { PHI_SPACE } from "../../../../theme/antd-css-var-contract";
 import { PHI_LAYOUT } from "../../../../theme/phi-tokens";
@@ -98,6 +99,7 @@ export async function buildPhiDefaultPubLoginPageTree({ page, presetKey, runtime
                 sortOrder: 0,
                 label: "pub login description widget",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     eyebrow: "Login",
                     title: "Sign in to your account",
                     description: "Access your customer workspace, orders, and account details.",

package/plugins/runtime-modules/auth/trees/phi-default-pub-registration-page-tree.js

@@ -1,3 +1,4 @@
+import { PHI_TEXT_SOURCE_PRESET } from "../../../../helpers/text-source";
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
 import { PHI_SPACE } from "../../../../theme/antd-css-var-contract";
 import { PHI_AUTH_RUNTIME_MODULE_ID } from "../ids";
@@ -68,6 +69,7 @@ export async function buildPhiDefaultPubRegistrationPageTree({ page, presetKey,
                 sortOrder: 0,
                 label: "pub registration description widget",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     eyebrow: "Register",
                     title: "Create account",
                     description: "Create your account to access your personalized workspace.",
@@ -113,6 +115,7 @@ export async function buildPhiDefaultPubRegistrationPageTree({ page, presetKey,
                 slotIndex: 1,
                 label: "pub registration notice",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     text: "We only use your details to create and support your account.",
                     tone: "secondary",
                 },

package/plugins/runtime-modules/auth/trees/phi-default-pub-reset-password-page-tree.js

@@ -1,3 +1,4 @@
+import { PHI_TEXT_SOURCE_PRESET } from "../../../../helpers/text-source";
 import { createPhiPresetCmsInstanceIdMap } from "../../../../types/cms-instance-id";
 import { PHI_SPACE } from "../../../../theme/antd-css-var-contract";
 import { PHI_AUTH_RUNTIME_MODULE_ID } from "../ids";
@@ -89,6 +90,7 @@ export async function buildPhiDefaultPubResetPasswordPageTree({ page, presetKey,
                 sortOrder: 0,
                 label: "pub reset password description widget",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     eyebrow: "Reset password",
                     title: "Choose a new password",
                     description: "Use the reset link from your email to choose a new secure password.",
@@ -113,6 +115,7 @@ export async function buildPhiDefaultPubResetPasswordPageTree({ page, presetKey,
                 slotIndex: 0,
                 label: "pub reset password intro",
                 config: {
+                    textSource: PHI_TEXT_SOURCE_PRESET,
                     text: "If the account exists, a reset email is on its way. Open the link in that email to choose a new password.",
                     tone: "secondary",
                     visibleWhen: withoutToken,

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

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { isPhiAuthoredTextField, readPhiTextSource } from "../../../../helpers/text-source";
 import { useEffect } from "react";
 import { PhiGeometryControl } from "../../../../components/controls/phi-geometry-control";
 import { PhiSurfaceControl } from "../../../../components/controls/phi-surface-control";
@@ -81,6 +82,14 @@ export function PhiDeveloperBuilderWidgetInspectorWidgetClient({ section, builde
             videoProviderDescriptors,
             onChange: (next) => {
                 const patch = buildPhiInspectorConfigPathPatch(currentWidgetSettingsConfigRecord, next);
+                /*
+                 * An author writing into a Preset's text makes the Widget's words the Site's: from here on the
+                 * Site's store translates them, not the global one (`helpers/text-source.ts`).
+                 */
+                if (readPhiTextSource(currentWidgetSettingsConfigRecord.textSource) != null
+                    && isPhiAuthoredTextField(field)) {
+                    patch.textSource = undefined;
+                }
                 onConfigChange?.(patch);
             },
         });

package/plugins/runtime-modules/builder/trees/phi-default-builder-area-preset-tree.js

@@ -1663,6 +1663,8 @@ async function buildPhiDefaultBuilderPagePresetTemplateTree({ page, runtime, pre
                             }),
                             nodes.widget({
                                 typeKey: "simple-text",
+                                /* Label set text, translated already; a second pass would hand the translator a non-source text. */
+                                flags: PhiCmsFlags.NoTranslate,
                                 id: PHI_BUILDER_MODULE_USAGE_WIDGET_IDS.moduleUsageIntro,
                                 parentLayoutNodeId: PHI_BUILDER_MODULE_USAGE_LAYOUT_IDS.moduleUsageBody,
                                 slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,
@@ -1737,6 +1739,8 @@ async function buildPhiDefaultBuilderPagePresetTemplateTree({ page, runtime, pre
                             }),
                             nodes.widget({
                                 typeKey: "simple-text",
+                                /* Label set text, translated already; a second pass would hand the translator a non-source text. */
+                                flags: PhiCmsFlags.NoTranslate,
                                 id: PHI_BUILDER_PUBLIC_ROUTES_WIDGET_IDS.publicRoutesIntro,
                                 parentLayoutNodeId: PHI_BUILDER_PUBLIC_ROUTES_LAYOUT_IDS.publicRoutesBody,
                                 slotIndex: PHI_CMS_DEFAULT_SLOT_INDEX,

package/plugins/runtime-modules/core/widgets/card/server.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { trBulk } from "../../../../../server-helpers/translate";
+import { trBulk, trBulkForLocale } from "../../../../../server-helpers/translate";
 import { isPhiMediaSvgContentType } from "../../../../../constants/media";
 import { resolvePhiImagePresentation } from "../../../../../components/media/image-presentation";
 import { resolvePhiPublicAssetReference } from "../../../../../components/widgets/helpers/internal-reference-resolver.server";
@@ -23,7 +23,9 @@ export async function PhiCardWidget({ labels, config, runtime, links, translate,
         ["actionLabel", actionEnabled ? ownActionLabel : undefined],
     ];
     const translatedTexts = translate
-        ? await trBulk(textEntries.map(([, value]) => value ?? ""))
+        ? await (runtime?.locale.current
+            ? trBulkForLocale(runtime.locale.current, textEntries.map(([, value]) => value ?? ""))
+            : trBulk(textEntries.map(([, value]) => value ?? "")))
         : textEntries.map(([, value]) => value ?? "");
     const translatedByKey = new Map(textEntries.map(([key], index) => [key, translatedTexts[index] || undefined]));
     /*

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

@@ -1,3 +1,4 @@
+import { type PhiTextSource } from "../../../../../helpers/text-source";
 import { type PhiCmsWidgetConfigBase } from "../../../../../components/widgets/config/parser-primitives";
 import { type PhiTextTone } from "../../../../../components/widgets/config/text-tone";
 import { type PhiBulletListEntry, type PhiBulletListStyle } from "../../../../../components/widgets/shared/bullet-list-vocabulary";
@@ -13,6 +14,8 @@ export type PhiCmsDescriptionWidgetConfig = PhiCmsWidgetConfigBase & {
     footer?: string;
     /** The tone of the description text; absent is the default secondary text. */
     tone?: PhiTextTone;
+    /** `"preset"` while the words are a Preset's and translated globally (`helpers/text-source.ts`). */
+    textSource?: PhiTextSource;
 };
 declare function parsePhiCmsDescriptionWidgetConfig(config: Record<string, unknown>): PhiCmsDescriptionWidgetConfig;
 export declare const PHI_DESCRIPTION_WIDGET_DEFINITION: {

package/plugins/runtime-modules/core/widgets/description/config.js

@@ -1,4 +1,5 @@
 import { resolvePhiCmsWidgetPluginKey } from "../../../../../constants/cms-widget-types";
+import { readPhiTextSource } from "../../../../../helpers/text-source";
 import { PhiCmsWidgetType } from "../../../../../constants/cms-widget-types";
 import { readRenderableBlockConfig, readString } from "../../../../../components/widgets/config/parser-primitives";
 import { PHI_TEXT_TONE_FIELD_OPTIONS, readPhiTextTone, } from "../../../../../components/widgets/config/text-tone";
@@ -15,6 +16,7 @@ function parsePhiCmsDescriptionWidgetConfig(config) {
         asideList: readPhiBulletListStyle(config.asideList),
         footer: readString(config.footer),
         tone: readPhiTextTone(config.tone),
+        textSource: readPhiTextSource(config.textSource),
     };
 }
 export const PHI_DESCRIPTION_WIDGET_DEFINITION = {