@phis/ui 0.2.0 → 0.3.0

package/components/widgets/client/shared/phi-link-target-control.js

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { PhiFlexControl } from "../../../controls/phi-flex-control";
+import { PhiSegmentedControl } from "../../../controls/phi-segmented-control";
+import { PhiSwitchControl } from "../../../controls/phi-switch-control";
+import { PhiTextControl } from "../../../controls/phi-text-control";
+import { PhiTreeSelectControl } from "../../../controls/phi-tree-select-control";
+import { isPhiStorableExternalHref, readPhiLinkTarget, } from "../../../../types/references";
+/**
+ * One link, chosen rather than typed, with the two answers it may have kept apart (`REFERENCES.md`).
+ *
+ * **The mode is held here and the value is not.** A target is written only once it is one: a Page with
+ * nothing picked yet and a half-typed address are both states somebody is passing through, and storing
+ * them would put a target in the config that resolves to nothing, index a reference that is not one, and
+ * draw a dead link between two keystrokes. So the segmented control remembers what the author is
+ * answering, and the value gets a target when the answer is complete -- or `undefined`, which is no link.
+ *
+ * Switching modes drops what the other one held rather than keeping it aside. A hidden address that
+ * returns when somebody flips back is a value nobody can see and nobody agreed to, and `REFERENCES.md`
+ * has no shape for a target that is two things at once.
+ *
+ * Which Pages it offers is the surface's knowledge: the Builder hands in its Area's catalog, a Form the
+ * tree `/api/site/page-references` answered. `area` is written into a Page target where the link leads
+ * out of the Area asking -- an Editor Form linking a Public Page.
+ */
+export function PhiLinkTargetControl({ value, options, labels, area, disabled, newTabRow = (control) => (_jsxs(PhiFlexControl, { align: "center", gap: 8, children: [control, _jsx("span", { children: labels.newTab })] })), onChange, }) {
+    const target = readPhiLinkTarget(value);
+    const [mode, setMode] = useState(target?.kind ?? "none");
+    /*
+     * The address as it is being typed, which the stored value cannot be: a target is only written when
+     * it is storable, so reading the box back out of the value would erase every character before the
+     * first one that makes a whole address.
+     */
+    const [draftHref, setDraftHref] = useState(target?.kind === "external" ? target.href : "");
+    /*
+     * The switch stands from the moment the author answers "Address", not only once an address is
+     * complete: it is part of the question. Until there is a target to carry it, its answer waits here.
+     */
+    const [pendingNewTab, setPendingNewTab] = useState(false);
+    /*
+     * The value can change under this control -- an undo, a Form reset, or the Inspector moving to another
+     * Widget of the same kind without remounting it. What this control wrote itself is already on screen;
+     * anything else replaces the mode and the address being typed, or they would go on showing, and
+     * writing into, the value before.
+     */
+    const valueKey = JSON.stringify(target ?? null);
+    const [syncedValueKey, setSyncedValueKey] = useState(valueKey);
+    const [emittedValueKey, setEmittedValueKey] = useState(null);
+    if (valueKey !== syncedValueKey) {
+        setSyncedValueKey(valueKey);
+        if (valueKey === emittedValueKey) {
+            // This control's own write came back; it is consumed, so a later return to the same value is news.
+            setEmittedValueKey(null);
+        }
+        else {
+            setMode(target?.kind ?? "none");
+            setDraftHref(target?.kind === "external" ? target.href : "");
+            setPendingNewTab(false);
+        }
+    }
+    const emit = (next, none) => {
+        setEmittedValueKey(JSON.stringify(next ?? null));
+        onChange?.(next, none);
+    };
+    const newTab = target ? target.newTab === true : pendingNewTab;
+    const withNewTab = (next) => (newTab ? { ...next, newTab: true } : next);
+    const changeMode = (nextMode) => {
+        setMode(nextMode);
+        setDraftHref("");
+        setPendingNewTab(false);
+        emit(undefined, nextMode === "none");
+    };
+    return (_jsxs(PhiFlexControl, { vertical: true, gap: 8, style: { width: "100%", minWidth: 0 }, children: [_jsx(PhiSegmentedControl, { value: mode, block: true, disabled: disabled || !onChange, options: [
+                    { value: "none", label: labels.none },
+                    { value: "page", label: labels.page },
+                    { value: "external", label: labels.external },
+                ], onChange: changeMode }), mode === "page" ? (_jsx(PhiTreeSelectControl, { value: target?.kind === "page" ? target.reference : null, options: options, placeholder: labels.pagePlaceholder, disabled: disabled || !onChange, allowClear: true, style: { width: "100%" }, onChange: (nextValue) => emit(nextValue
+                    ? { kind: "page", reference: nextValue, ...(area ? { area } : {}) }
+                    : undefined) })) : null, mode === "external" ? (_jsx(PhiTextControl, { value: draftHref, inputType: "url", placeholder: labels.externalPlaceholder, disabled: disabled || !onChange, style: { width: "100%" }, onChange: (nextValue) => {
+                    const href = nextValue ?? "";
+                    setDraftHref(href);
+                    emit(isPhiStorableExternalHref(href)
+                        ? withNewTab({ kind: "external", href: href.trim() })
+                        : undefined);
+                } })) : null, mode === "external" ? newTabRow(_jsx(PhiSwitchControl, { checked: newTab, disabled: disabled || !onChange, onChange: (checked) => {
+                    if (target?.kind !== "external") {
+                        setPendingNewTab(checked);
+                        return;
+                    }
+                    emit(checked ? { ...target, newTab: true } : { ...target, newTab: undefined });
+                } })) : null] }));
+}

package/components/widgets/client/shared/phi-mask-picker.js

@@ -1,29 +1,23 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useState } from "react";
-import { StarOutlined } from "@ant-design/icons";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { PhiMediaAssetFlags, PhiMediaAssetSource, PhiMediaKind } from "../../../../constants/media";
 import { normalizePhiImagePreviewTile } from "../../../media/phi-image-preview-data";
 import { bumpPhiImagePreviewRefreshToken } from "../../../media/phi-image-preview-store";
 import { usePhiMediaPickerBinding } from "../../../media/phi-media-picker-binding";
-import { runPhiMediaUploadSession } from "../../../media/media-upload-flow";
+import { isPhiMediaUploadCancelled, runPhiMediaUploadSession } from "../../../media/media-upload-flow";
 import { PHI_MEDIA_UPLOAD_DEFAULT_LABELS, readPhiMediaUploadErrorMessage, } from "../../../media/phi-media-upload";
 import { PHI_MEDIA_WIDGET_DEFAULT_LABELS } from "../../../media/media-widget-labels";
 import { PHI_SEARCH_WIDGET_DEFAULT_LABELS } from "../../label-types/search";
-import { mergePhiMaskConfigDefaults, } from "../../config/mask";
+import { mergePhiMaskConfigPatch, } from "../../config/mask";
 import { PhiMaskPickerControl } from "../../../controls/phi-mask-picker-control";
 import { usePhiApplicationFeedback } from "../../../runtime/use-phi-application-feedback";
 import { usePhiWidgetScaffoldPopup } from "./phi-widget-scaffold-popup";
+import { usePhiAuthoringToolsLabels } from "./phi-authoring-tools-labels";
 import { createPhiMediaPickerAssetControllerRoutes } from "../../../media/asset-controller-routes";
+import { PhiIcon } from "../../../shell/phi-icon";
 const PHI_MASK_PICKER_MEDIA_ROUTES = createPhiMediaPickerAssetControllerRoutes("mask-picker-media", "area");
 const PHI_MASK_MEDIA_SCOPE_KEY = "image-mask-picker";
-function mergeMask(value, patch) {
-    return {
-        ...mergePhiMaskConfigDefaults(value),
-        ...patch,
-        enabled: patch.enabled ?? true,
-    };
-}
 function parseIconifyIcon(value) {
     if (!value?.startsWith("iconify:"))
         return null;
@@ -44,14 +38,47 @@ function buildIconifySvgUrl(icon) {
 function buildIconifyMaskFilename(icon) {
     return `${icon.iconSet}-${icon.iconName}`.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "icon-mask";
 }
-export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, buttonAriaLabel = "Select mask", buttonIcon = _jsx(StarOutlined, {}), placement = "bottomRight", }) {
+export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, buttonAriaLabel, buttonIcon = _jsx(PhiIcon, { name: "star", size: "inherit" }), placement = "bottomRight", }) {
     const { showMessage } = usePhiApplicationFeedback();
     const popup = usePhiWidgetScaffoldPopup();
+    const toolLabels = usePhiAuthoringToolsLabels();
+    const iconifyRequiredMessage = toolLabels.mask.iconifyRequired;
     const [open, setOpen] = useState(false);
     const [mediaOpen, setMediaOpen] = useState(false);
     const [uploading, setUploading] = useState(false);
     const [uploadProgress, setUploadProgress] = useState(0);
     const [selectedIcon, setSelectedIcon] = useState(null);
+    /*
+     * The value as it stands when an upload lands, not as it stood when the upload began: scale, offset
+     * and rotation can be changed while the file travels, and the Asset is merged into what is there.
+     */
+    const valueRef = useRef(value);
+    useEffect(() => {
+        valueRef.current = value;
+    }, [value]);
+    /*
+     * One upload at a time. A second file or icon while one travels is not taken -- the controls are
+     * disabled, and this holds for a drop that arrives before they re-render -- so two Assets can never
+     * race for the mask. Leaving the picker stops the upload; the Server clears up what arrived.
+     */
+    const uploadRef = useRef(null);
+    useEffect(() => () => uploadRef.current?.abort(), []);
+    const beginUpload = useCallback(() => {
+        if (uploadRef.current)
+            return null;
+        const controller = new AbortController();
+        uploadRef.current = controller;
+        setUploading(true);
+        setUploadProgress(0);
+        return controller;
+    }, []);
+    const endUpload = useCallback((controller) => {
+        if (uploadRef.current !== controller)
+            return;
+        uploadRef.current = null;
+        setUploading(false);
+        setUploadProgress(0);
+    }, []);
     const updateOpen = useCallback((nextOpen) => {
         setOpen(nextOpen);
         if (!nextOpen)
@@ -59,15 +86,15 @@ export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, butt
         popup.setOpen(nextOpen);
     }, [popup]);
     const applyAsset = useCallback((asset) => {
-        onChange(mergeMask(value, {
+        onChange(mergePhiMaskConfigPatch(valueRef.current, {
             source: "asset",
             assetId: asset.id,
             assetUrl: asset.deliveryUrl,
         }));
         updateOpen(false);
-    }, [onChange, updateOpen, value]);
+    }, [onChange, updateOpen]);
     const clearAsset = useCallback(() => {
-        onChange(mergeMask(value, {
+        onChange(mergePhiMaskConfigPatch(value, {
             source: "preset",
             preset: "circle",
             assetId: undefined,
@@ -97,33 +124,36 @@ export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, butt
         applyAsset(tile);
     }, [applyAsset]);
     const uploadFile = useCallback((file) => {
-        setUploading(true);
-        setUploadProgress(0);
-        void runPhiMediaUploadSession(file, setUploadProgress, { presentationFlags: PhiMediaAssetFlags.Mask }).then((result) => {
+        const controller = beginUpload();
+        if (!controller)
+            return;
+        void runPhiMediaUploadSession(file, setUploadProgress, { presentationFlags: PhiMediaAssetFlags.Mask }, controller.signal).then((result) => {
+            if (controller.signal.aborted)
+                return;
             applyUploadedAsset(result.asset);
             showMessage({ level: "success", content: `Uploaded ${file.name}.` });
         }).catch((error) => {
+            if (controller.signal.aborted || isPhiMediaUploadCancelled(error))
+                return;
             // One reading of every refusal, rather than whatever string the control plane happened to send.
             showMessage({
                 level: "error",
                 content: readPhiMediaUploadErrorMessage(error, PHI_MEDIA_UPLOAD_DEFAULT_LABELS),
             });
-        }).finally(() => {
-            setUploading(false);
-            setUploadProgress(0);
-        });
-    }, [applyUploadedAsset, showMessage]);
+        }).finally(() => endUpload(controller));
+    }, [applyUploadedAsset, beginUpload, endUpload, showMessage]);
     const uploadIconifyMask = useCallback((nextIconValue) => {
         setSelectedIcon(nextIconValue);
         const icon = parseIconifyIcon(nextIconValue);
         if (!icon) {
             if (nextIconValue)
-                showMessage({ level: "error", content: "Select an Iconify icon for mask uploads." });
+                showMessage({ level: "error", content: iconifyRequiredMessage });
             return;
         }
-        setUploading(true);
-        setUploadProgress(0);
-        void fetch(buildIconifySvgUrl(icon), { cache: "force-cache" })
+        const controller = beginUpload();
+        if (!controller)
+            return;
+        void fetch(buildIconifySvgUrl(icon), { cache: "force-cache", signal: controller.signal })
             .then(async (response) => {
             if (!response.ok)
                 throw new Error(`Iconify SVG request failed with ${response.status}.`);
@@ -140,22 +170,23 @@ export function PhiMaskPickerButton({ value, onChange, onCommit, onDiscard, butt
                     },
                     usage: { mask: true },
                 },
-            });
+            }, controller.signal);
         })
             .then((result) => {
+            if (controller.signal.aborted)
+                return;
             applyUploadedAsset(result.asset);
             showMessage({ level: "success", content: `Selected ${icon.iconKey}.` });
         })
             .catch((error) => {
+            if (controller.signal.aborted || isPhiMediaUploadCancelled(error))
+                return;
             showMessage({
                 level: "error",
                 content: readPhiMediaUploadErrorMessage(error, PHI_MEDIA_UPLOAD_DEFAULT_LABELS),
             });
         })
-            .finally(() => {
-            setUploading(false);
-            setUploadProgress(0);
-        });
-    }, [applyUploadedAsset, showMessage]);
-    return (_jsx(PhiMaskPickerControl, { value: value, open: open, placement: placement, buttonAriaLabel: buttonAriaLabel, buttonIcon: buttonIcon, mediaPickerProps: mediaPickerProps, selectedIcon: selectedIcon, uploading: uploading, uploadProgress: uploadProgress, popupRootClassName: popup.rootClassName, getPopupContainer: popup.getPopupContainer, onUploadFile: uploadFile, onIconSelect: uploadIconifyMask, onChange: onChange, onCommit: onCommit, onDiscard: onDiscard, onOpenChange: updateOpen }));
+            .finally(() => endUpload(controller));
+    }, [applyUploadedAsset, beginUpload, endUpload, iconifyRequiredMessage, showMessage]);
+    return (_jsx(PhiMaskPickerControl, { value: value, open: open, placement: placement, buttonAriaLabel: buttonAriaLabel ?? toolLabels.mask.select, buttonIcon: buttonIcon, mediaPickerProps: mediaPickerProps, selectedIcon: selectedIcon, uploading: uploading, uploadProgress: uploadProgress, popupRootClassName: popup.rootClassName, getPopupContainer: popup.getPopupContainer, onUploadFile: uploadFile, onIconSelect: uploadIconifyMask, onChange: onChange, onCommit: onCommit, onDiscard: onDiscard, onOpenChange: updateOpen }));
 }

package/components/widgets/client/shared/phi-page-reference-picker.js

@@ -1,10 +1,10 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { LinkOutlined } from "@ant-design/icons";
 import { createContext, useContext, useState } from "react";
 import { PhiButtonControl } from "../../../controls/phi-button-control";
 import { PhiPopoverControl } from "../../../controls/phi-popover-control";
 import { PhiTreeSelectControl } from "../../../controls/phi-tree-select-control";
+import { PhiIcon } from "../../../shell/phi-icon";
 /*
  * The Pages an authoring surface offers to link to.
  *
@@ -28,5 +28,5 @@ export function PhiPageReferencePicker({ ariaLabel = "Select internal Page", onS
                     return;
                 onSelect(option.meta);
                 setOpen(false);
-            } })), children: _jsx("span", { style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel, icon: _jsx(LinkOutlined, {}), onClick: () => undefined }) }) }));
+            } })), children: _jsx("span", { style: { display: "inline-flex" }, children: _jsx(PhiButtonControl, { type: "text", size: "small", ariaLabel: ariaLabel, icon: _jsx(PhiIcon, { name: "link", size: "inherit" }), onClick: () => undefined }) }) }));
 }

package/components/widgets/client/shared/phi-rendered-value.d.ts

@@ -26,18 +26,4 @@ export type PhiRenderedValueDefinition = {
  * it could not have simply called the table's renderer.
  */
 export type PhiRenderedValuePresentation = "cell" | "block";
-/**
- * **A flag being read is a mark, not a switch.**
- *
- * `switch` and `checkbox` drew the Controls of those names with `readOnly`, which cost twice. A switch
- * nobody can throw still looks like one, and a screen reader announces it as an operable widget; and the
- * import put two editing Controls into the bundle of every Widget that shows a value, which is why
- * `validate-area-client-reach.mjs` could not list the record Widget among the ones that only display.
- *
- * The two renderers draw the same mark here, and that is the truth rather than a loss: read-only, a
- * switch and a checkbox both say the same thing -- this flag is set. Their difference is how you operate
- * them, and where a cell can be operated the table hands it to `EditableTableCell`, which still draws the
- * Control the author asked for.
- */
-export declare function normalizePhiRenderedText(value: unknown): string;
 export declare function renderPhiValueContent(value: unknown, definition: PhiRenderedValueDefinition, presentation?: PhiRenderedValuePresentation): ReactNode;

package/components/widgets/client/shared/phi-rendered-value.js

@@ -21,7 +21,7 @@ import { isPhiRecord } from "../../../../helpers/is-record";
  * them, and where a cell can be operated the table hands it to `EditableTableCell`, which still draws the
  * Control the author asked for.
  */
-export function normalizePhiRenderedText(value) {
+function normalizePhiRenderedText(value) {
     if (value == null)
         return "";
     if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")

package/components/widgets/client/shared/phi-static-table-provider.d.ts

@@ -1,21 +1,10 @@
 import type { PhiRuntimeDataProviderKey } from "../../../../types/runtime-data-provider";
-import { type PhiTableProviderMutationRequest, type PhiTableProviderRecordRequest, type PhiTableProviderMutationResult, type PhiTableProviderQueryRequest, type PhiTableProviderResourceDescriptor } from "../../../../types/table-widget";
+import { type PhiTableProviderMutationRequest, type PhiTableProviderMutationResult, type PhiTableProviderQueryRequest, type PhiTableProviderResourceDescriptor } from "../../../../types/table-widget";
 import type { PhiTableProviderRegistration } from "./phi-table-provider";
 export type PhiStaticTableResource = {
     descriptor: PhiTableProviderResourceDescriptor;
     rows: readonly Record<string, unknown>[];
 };
-/**
- * One row by its identity.
- *
- * **The rows are already here, so the only thing this ever lacked was the method.** A Provider declaring
- * `recordRead` without a `readRecord` is a capability that answers nothing, and until the record Widget
- * asked for it no static resource had a reason to notice -- which is why the contract says a Site can
- * read a record without a server and, for the static path, it could not.
- */
-export declare function readPhiStaticTableRecord(resource: PhiStaticTableResource, request: PhiTableProviderRecordRequest): {
-    [x: string]: unknown;
-};
 export declare function queryPhiStaticTableResource(resource: PhiStaticTableResource, request: PhiTableProviderQueryRequest): {
     rows: Record<string, unknown>[];
     total: number;

package/components/widgets/client/shared/phi-static-table-provider.js

@@ -1,9 +1,5 @@
+import { readPhiDotPath } from "../../../../helpers/dot-path";
 import { PhiTableProviderError, } from "../../../../types/table-widget";
-function readValue(row, path) {
-    return path.split(".").filter(Boolean).reduce((current, segment) => current && typeof current === "object" && !Array.isArray(current)
-        ? current[segment]
-        : undefined, row);
-}
 /*
  * One ordering for a column whatever its cells hold: two numbers compare as numbers, anything else as
  * text with digit runs read as numbers, so `9` sits before `10` whether it arrived as a number or a
@@ -32,7 +28,7 @@ function preserveMatchingAncestry(rows, matches, resource) {
     if (!parentPath)
         return matches;
     const byIdentity = new Map(rows.flatMap((row) => {
-        const identity = readValue(row, resource.rowIdentityPath);
+        const identity = readPhiDotPath(row, resource.rowIdentityPath);
         return typeof identity === "string" || typeof identity === "number"
             ? [[String(identity), row]]
             : [];
@@ -42,7 +38,7 @@ function preserveMatchingAncestry(rows, matches, resource) {
         let current = byIdentity.get(identity);
         const visited = new Set();
         while (current) {
-            const parent = readValue(current, parentPath);
+            const parent = readPhiDotPath(current, parentPath);
             if (typeof parent !== "string" && typeof parent !== "number")
                 break;
             const parentIdentity = String(parent);
@@ -60,13 +56,13 @@ function orderHierarchyRows(rows, resource) {
     if (!parentPath)
         return [...rows];
     const identities = new Set(rows.flatMap((row) => {
-        const identity = readValue(row, resource.rowIdentityPath);
+        const identity = readPhiDotPath(row, resource.rowIdentityPath);
         return typeof identity === "string" || typeof identity === "number" ? [String(identity)] : [];
     }));
     const children = new Map();
     const roots = [];
     for (const row of rows) {
-        const parent = readValue(row, parentPath);
+        const parent = readPhiDotPath(row, parentPath);
         const parentIdentity = typeof parent === "string" || typeof parent === "number" ? String(parent) : null;
         if (!parentIdentity || !identities.has(parentIdentity)) {
             roots.push(row);
@@ -79,7 +75,7 @@ function orderHierarchyRows(rows, resource) {
     const ordered = [];
     const visited = new Set();
     const append = (row) => {
-        const identity = readValue(row, resource.rowIdentityPath);
+        const identity = readPhiDotPath(row, resource.rowIdentityPath);
         const key = typeof identity === "string" || typeof identity === "number" ? String(identity) : null;
         if (!key || visited.has(key))
             return;
@@ -102,12 +98,12 @@ function orderHierarchyRows(rows, resource) {
  * asked for it no static resource had a reason to notice -- which is why the contract says a Site can
  * read a record without a server and, for the static path, it could not.
  */
-export function readPhiStaticTableRecord(resource, request) {
+function readPhiStaticTableRecord(resource, request) {
     const identity = request.rowIdentity;
     if (identity == null) {
         throw new PhiTableProviderError("row-not-found", `Static Table resource "${request.resourceKey}" was asked for a record without a row identity.`);
     }
-    const row = resource.rows.find((candidate) => String(readValue(candidate, resource.descriptor.rowIdentityPath) ?? "") === String(identity));
+    const row = resource.rows.find((candidate) => String(readPhiDotPath(candidate, resource.descriptor.rowIdentityPath) ?? "") === String(identity));
     if (!row) {
         throw new PhiTableProviderError("row-not-found", `Static Table resource "${request.resourceKey}" has no row "${identity}".`);
     }
@@ -118,10 +114,13 @@ export function queryPhiStaticTableResource(resource, request) {
     const search = request.query.search?.trim().toLocaleLowerCase();
     const matchingIdentities = new Set();
     for (const row of rows) {
-        const matchesSearch = !search || Object.values(row).some((value) => String(value ?? "").toLocaleLowerCase().includes(search));
-        const matchesFilters = Object.entries(request.query.filters ?? {}).every(([key, filter]) => matchesFilter(readValue(row, key), filter));
+        // Only what a cell shows as text is searched: an object field read as "[object Object]" and
+        // matched every search for "object".
+        const matchesSearch = !search || Object.values(row).some((value) => (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+            && String(value).toLocaleLowerCase().includes(search));
+        const matchesFilters = Object.entries(request.query.filters ?? {}).every(([key, filter]) => matchesFilter(readPhiDotPath(row, key), filter));
         if (matchesSearch && matchesFilters) {
-            const identity = readValue(row, resource.descriptor.rowIdentityPath);
+            const identity = readPhiDotPath(row, resource.descriptor.rowIdentityPath);
             if (typeof identity === "string" || typeof identity === "number") {
                 matchingIdentities.add(String(identity));
             }
@@ -129,14 +128,14 @@ export function queryPhiStaticTableResource(resource, request) {
     }
     const visibleIdentities = preserveMatchingAncestry(rows, matchingIdentities, resource.descriptor);
     rows = rows.filter((row) => {
-        const identity = readValue(row, resource.descriptor.rowIdentityPath);
+        const identity = readPhiDotPath(row, resource.descriptor.rowIdentityPath);
         return (typeof identity === "string" || typeof identity === "number") &&
             visibleIdentities.has(String(identity));
     });
     if (request.query.sorts?.length) {
         rows.sort((left, right) => {
             for (const sort of request.query.sorts ?? []) {
-                const comparison = compareSortValues(readValue(left, sort.key), readValue(right, sort.key), sort.direction);
+                const comparison = compareSortValues(readPhiDotPath(left, sort.key), readPhiDotPath(right, sort.key), sort.direction);
                 if (comparison !== 0)
                     return comparison;
             }

package/components/widgets/client/shared/phi-table-provider-request.d.ts

@@ -0,0 +1,11 @@
+import type { PhiTableQuery } from "../../../../types/table-widget";
+/** A string filter the Table sent, trimmed; anything else is no filter. */
+export declare function readPhiTableStringFilter(query: PhiTableQuery, key: string): string;
+/** The rows of an answer: every record in the array, nothing else. */
+export declare function readPhiTableRows(value: unknown): Record<string, unknown>[];
+/** A positive integer, as a number or as the string a filter or row identity carries it in; else none. */
+export declare function readPhiPositiveInteger(value: unknown): number | null;
+/** The request a Table Provider sends a Site route: fresh, with the Site session, asking for JSON. */
+export declare function createPhiTableProviderRequestInit(signal: AbortSignal | undefined): RequestInit;
+/** `page` and `pageSize` as a route reads them, with the Table's defaults where the query names none. */
+export declare function buildPhiTablePageParams(query: PhiTableQuery, defaultPageSize?: number): URLSearchParams;

package/components/widgets/client/shared/phi-table-provider-request.js

@@ -0,0 +1,43 @@
+import { isPhiRecord } from "../../../../helpers/is-record";
+/*
+ * What every Table Provider does on its way to its route, written once.
+ *
+ * Six Providers carried these word for word: how a filter is read, how an answer's rows are kept to the
+ * records among them, how a positive integer arrives as a number or as the string a filter carries it
+ * in, what a request to a Site route looks like, and how a page is named. One copy means one answer --
+ * a Provider that reads a filter differently is making a different claim, and should have to say so.
+ */
+/** A string filter the Table sent, trimmed; anything else is no filter. */
+export function readPhiTableStringFilter(query, key) {
+    const value = query.filters?.[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+/** The rows of an answer: every record in the array, nothing else. */
+export function readPhiTableRows(value) {
+    return Array.isArray(value) ? value.filter(isPhiRecord) : [];
+}
+/** A positive integer, as a number or as the string a filter or row identity carries it in; else none. */
+export function readPhiPositiveInteger(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+        return value;
+    if (typeof value !== "string")
+        return null;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+/** The request a Table Provider sends a Site route: fresh, with the Site session, asking for JSON. */
+export function createPhiTableProviderRequestInit(signal) {
+    return {
+        cache: "no-store",
+        credentials: "include",
+        headers: { accept: "application/json" },
+        signal,
+    };
+}
+/** `page` and `pageSize` as a route reads them, with the Table's defaults where the query names none. */
+export function buildPhiTablePageParams(query, defaultPageSize = 25) {
+    return new URLSearchParams({
+        page: String(query.page && query.page > 0 ? query.page : 1),
+        pageSize: String(query.pageSize && query.pageSize > 0 ? query.pageSize : defaultPageSize),
+    });
+}

package/components/widgets/client/shared/phi-timeline-provider.d.ts

@@ -0,0 +1,36 @@
+import { type ComponentType, type ReactNode } from "react";
+import { type PhiTimelineEntry, type PhiTimelineProviderResult } from "@phis/contracts/timeline";
+import { type PhiRuntimeDataProviderBinding, type PhiRuntimeDataProviderKey } from "../../../../types/runtime-data-provider";
+export type PhiTimelineProviderRequest = {
+    scopeKey?: string;
+    params?: Record<string, unknown>;
+};
+export type PhiTimelineProviderRegistration = {
+    key: PhiRuntimeDataProviderKey;
+    load: (request: PhiTimelineProviderRequest) => Promise<PhiTimelineProviderResult>;
+    /**
+     * What the answer depends on beyond scope and params -- a revision the Module bumps when its data
+     * changes. Left out, the same request is answered once for every Widget that asks it.
+     */
+    resolveLoadKey?: (request: PhiTimelineProviderRequest) => string;
+};
+export declare function createPhiTimelineProviderClient(registration: PhiTimelineProviderRegistration): ComponentType<{
+    children: ReactNode;
+}>;
+export declare function PhiTimelineProviderClient({ registration, children, }: {
+    registration: PhiTimelineProviderRegistration;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<ReadonlyMap<`${string}/${string}`, PhiTimelineProviderRegistration>>>;
+export declare function PhiTimelineProviderIsolationBoundary({ children }: {
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<ReadonlyMap<`${string}/${string}`, PhiTimelineProviderRegistration>>>;
+export type PhiTimelineProviderEntries = {
+    entries: PhiTimelineEntry[];
+    loading: boolean;
+    /** Why there are no entries from the Provider, for the author: not configured, not active, failed. */
+    error: string | null;
+    /** Asks the Provider again, for a Widget told its data changed. */
+    reload: () => void;
+};
+/** The entries a bound Timeline Provider answers; `null` binding is no Provider and no entries. */
+export declare function usePhiTimelineProviderEntries(binding: PhiRuntimeDataProviderBinding | null): PhiTimelineProviderEntries;