@phis/ui 0.1.0 → 0.2.1

package/components/widgets/client/shared/phi-control-signal-routing.d.ts

@@ -0,0 +1,35 @@
+import type { PhiSignal, PhiSignalValue } from "../../../../types";
+import type { PhiSignalRoute } from "../../../../types/signals";
+/**
+ * What a signal a Control receives asks it to do.
+ *
+ * Read from `channel` and `action` alone. The value is data and never a command: a text Control told
+ * `value/change` with the string `"clear"` shows the word "clear", it does not empty itself. Clearing is
+ * `action: "clear"`, toggling is `action: "toggle"`, enabling is `enabled/change` with a boolean, focus
+ * is `focused/change` with a boolean ([SIGNALS.md](../../../../SIGNALS.md#actions)).
+ */
+export type PhiControlSignalCommand = {
+    kind: "clear";
+} | {
+    kind: "toggle";
+} | {
+    kind: "focus";
+} | {
+    kind: "blur";
+} | {
+    kind: "enabled";
+    enabled: boolean;
+} | {
+    kind: "set";
+    value: PhiSignalValue;
+};
+/**
+ * The listen route a delivered signal arrived through, or `null` when none of this Control's routes
+ * carries it.
+ *
+ * Every addressing fact on the route has to agree: scope, channel, action, value type, and for `json`
+ * the value schema. Scope is part of it because the bus puts the receiver's registered scope on the signal,
+ * so a route written for another scope is not the wire the signal came through.
+ */
+export declare function findPhiControlListenRoute(listenRoutes: readonly PhiSignalRoute[], signal: Pick<PhiSignal, "scope" | "channel" | "action" | "valueType" | "valueSchema">): PhiSignalRoute | null;
+export declare function readPhiControlSignalCommand(signal: Pick<PhiSignal, "channel" | "action" | "value">): PhiControlSignalCommand | null;

package/components/widgets/client/shared/phi-control-signal-routing.js

@@ -0,0 +1,35 @@
+/**
+ * The listen route a delivered signal arrived through, or `null` when none of this Control's routes
+ * carries it.
+ *
+ * Every addressing fact on the route has to agree: scope, channel, action, value type, and for `json`
+ * the value schema. Scope is part of it because the bus puts the receiver's registered scope on the signal,
+ * so a route written for another scope is not the wire the signal came through.
+ */
+export function findPhiControlListenRoute(listenRoutes, signal) {
+    return listenRoutes.find((candidate) => candidate.receiver !== null &&
+        candidate.scope === signal.scope &&
+        candidate.channel === signal.channel &&
+        candidate.action === signal.action &&
+        candidate.valueType === signal.valueType &&
+        (candidate.valueType !== "json" ||
+            (candidate.valueSchema != null && candidate.valueSchema === signal.valueSchema))) ?? null;
+}
+export function readPhiControlSignalCommand(signal) {
+    if (signal.action === "clear") {
+        return { kind: "clear" };
+    }
+    if (signal.action === "toggle") {
+        return { kind: "toggle" };
+    }
+    if (signal.action !== "change") {
+        return null;
+    }
+    if (signal.channel === "focused") {
+        return signal.value === false ? { kind: "blur" } : { kind: "focus" };
+    }
+    if (signal.channel === "enabled") {
+        return typeof signal.value === "boolean" ? { kind: "enabled", enabled: signal.value } : null;
+    }
+    return { kind: "set", value: signal.value };
+}

package/components/widgets/client/shared/phi-control-signals.d.ts

@@ -1,7 +1,6 @@
 import type { PhiSignal, PhiSignalScope, PhiSignalChannel, PhiSignalValue, PhiSignalValueType } from "../../../../types";
 import type { PhiSignalAddress, PhiSignalRouteSet } from "../../../../types/signals";
 export type PhiControlSignalEventValue = "submit" | "focus" | "blur" | "clear";
-export type PhiControlSignalCommandValue = "clear" | "enable" | "disable" | "toggle";
 export type PhiControlSignalControllerOptions<TValue> = {
     key?: string | null;
     valueType?: PhiSignalValueType | null;

package/components/widgets/client/shared/phi-control-signals.js

@@ -1,17 +1,9 @@
 "use client";
 import { useCallback, useMemo, useState } from "react";
-import { findPhiSignalRoutesByCapabilityId } from "../../../../types/signals";
+import { findPhiSignalRoutesByCapabilityId, resolvePhiSignalRouteValue, } from "../../../../types/signals";
 import { usePhiSignalListener } from "../../../runtime/runtime-signal-bus";
 import { usePhiSignalEmitter, usePhiSignalIdentity } from "../../../runtime/runtime-signal-identity";
-function isPhiControlCommandValue(value) {
-    if (value === "clear" ||
-        value === "enable" ||
-        value === "disable" ||
-        value === "toggle") {
-        return true;
-    }
-    return false;
-}
+import { findPhiControlListenRoute, readPhiControlSignalCommand } from "./phi-control-signal-routing";
 function defaultCoerceValue(value) {
     return value;
 }
@@ -43,7 +35,7 @@ export function usePhiControlSignalController({ key, valueType = "string", sende
                 scope: route.scope,
                 channel: route.channel,
                 action: route.action ?? action,
-                value: route.valueType === "none" ? null : value,
+                value: resolvePhiSignalRouteValue(route, value),
                 valueType: nextValueType ?? route.valueType ?? (value == null ? "none" : signalValueType),
                 valueSchema: route.valueSchema ?? null,
                 receiver: route.receiver,
@@ -61,73 +53,47 @@ export function usePhiControlSignalController({ key, valueType = "string", sende
         if (!signalsEnabled || listenRoutes.length === 0) {
             return;
         }
-        const route = listenRoutes.find((candidate) => candidate.channel === signal.channel &&
-            candidate.action === signal.action &&
-            candidate.valueType === signal.valueType &&
-            (candidate.valueType !== "json" ||
-                (candidate.valueSchema != null && candidate.valueSchema === signal.valueSchema)) &&
-            candidate.receiver !== null);
+        const route = findPhiControlListenRoute(listenRoutes, signal);
         if (!route) {
             return;
         }
-        const action = signal.action;
-        const value = signal.value;
-        const targetsCurrentControl = signal.receiver === "broadcast" || (signalSender != null && signal.receiver === signalSender);
+        const targetsCurrentControl = signal.receiver === "broadcast" ||
+            (signalSender != null && signal.receiver === signalSender);
         if (!targetsCurrentControl) {
             return;
         }
         if (onReceiveCapability?.(route.capabilityId, signal) === true) {
             return;
         }
-        if (action === "clear" || value === "clear") {
-            onClear?.();
-            if (clearValue !== undefined) {
-                onSetValue?.(clearValue);
-            }
-            return;
-        }
-        if (signal.channel === "focused" && action === "change") {
-            if (value === false) {
-                onBlurRequest?.();
-            }
-            else {
+        const command = readPhiControlSignalCommand(signal);
+        switch (command?.kind) {
+            case "clear":
+                onClear?.();
+                if (clearValue !== undefined) {
+                    onSetValue?.(clearValue);
+                }
+                return;
+            case "focus":
                 onFocusRequest?.();
-            }
-            return;
-        }
-        if (signal.channel === "focused" && value === true) {
-            onFocusRequest?.();
-            return;
-        }
-        if (signal.channel === "focused" && value === false) {
-            onBlurRequest?.();
-            return;
-        }
-        if (action === "change" && signal.channel === "enabled") {
-            setCommandDisabled(typeof value === "boolean" ? !value : false);
-            return;
-        }
-        if (action === "toggle" || value === "toggle") {
-            onToggleRequest?.();
-            return;
-        }
-        const command = value;
-        if (action === "change") {
-            const nextValue = coerceValue(value);
-            if (nextValue != null) {
-                onSetValue?.(nextValue);
-            }
-            return;
-        }
-        if (isPhiControlCommandValue(command)) {
-            if (command === "enable") {
-                setCommandDisabled(false);
                 return;
-            }
-            if (command === "disable") {
-                setCommandDisabled(true);
+            case "blur":
+                onBlurRequest?.();
+                return;
+            case "enabled":
+                setCommandDisabled(!command.enabled);
+                return;
+            case "toggle":
+                onToggleRequest?.();
+                return;
+            case "set": {
+                const nextValue = coerceValue(command.value);
+                if (nextValue != null) {
+                    onSetValue?.(nextValue);
+                }
                 return;
             }
+            default:
+                return;
         }
     }, [
         clearValue,

package/components/widgets/client/shared/phi-input-signals.d.ts

@@ -1,7 +1,4 @@
 import type { PhiSignalAddress, PhiSignalRouteSet, PhiSignalScope } from "../../../../types";
-import { type PhiControlSignalCommandValue, type PhiControlSignalEventValue } from "./phi-control-signals";
-export type PhiInputSignalEventValue = PhiControlSignalEventValue;
-export type PhiInputSignalCommandValue = PhiControlSignalCommandValue;
 export type PhiInputSignalControllerOptions = {
     key?: string | null;
     sender?: PhiSignalAddress | null;

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

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import type { PhiPageReference } from "../../../../types/references";
+import type { PhiTreeOption } from "../../../../types/tree";
+/** A Page picked to link to: its reference, and what to show for it. */
+export type PhiPageReferenceSelection = {
+    reference: PhiPageReference;
+    title: string;
+    path: string;
+};
+export declare function PhiAuthoringPageReferencesProvider({ options, children, }: {
+    options: readonly PhiTreeOption<PhiPageReferenceSelection>[];
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The link button that picks an internal Page. A surface that offers no Pages shows none. */
+export declare function PhiPageReferencePicker({ ariaLabel, onSelect, }: {
+    ariaLabel?: string;
+    onSelect: (selection: PhiPageReferenceSelection) => void;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,32 @@
+"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";
+/*
+ * The Pages an authoring surface offers to link to.
+ *
+ * Which Pages those are is the surface's knowledge, not the tool button's: the Builder knows its Area's
+ * catalog, and a tool button inside a Widget's authoring knows nothing of the Builder and must not. The
+ * surface provides the tree beside the tool labels, so a picker is inside it for the same reason.
+ */
+const PhiAuthoringPageReferencesContext = createContext(null);
+export function PhiAuthoringPageReferencesProvider({ options, children, }) {
+    return (_jsx(PhiAuthoringPageReferencesContext.Provider, { value: options, children: children }));
+}
+/** The link button that picks an internal Page. A surface that offers no Pages shows none. */
+export function PhiPageReferencePicker({ ariaLabel = "Select internal Page", onSelect, }) {
+    const options = useContext(PhiAuthoringPageReferencesContext);
+    const [open, setOpen] = useState(false);
+    if (!options) {
+        return null;
+    }
+    return (_jsx(PhiPopoverControl, { open: open, trigger: "click", placement: "bottomRight", onOpenChange: setOpen, content: (_jsx(PhiTreeSelectControl, { ariaLabel: ariaLabel, placeholder: "Select Page", options: [...options], popupMatchSelectWidth: 320, style: { width: 280 }, onChange: (_value, option) => {
+                if (!option?.meta)
+                    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 }) }) }));
+}

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

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+import type { PhiTableTagColor, PhiTableTagVariant, PhiTableValueRenderer } from "../../../../types/table-widget";
+/**
+ * How one value out of a Provider is drawn: a date as a date, an address as a link, a set of words as
+ * tags, a flag as a switch.
+ *
+ * **It is the table's vocabulary, and it was the table's alone.** A record of the same rows -- the same
+ * Provider, the same fields, one row instead of many -- would have had to write every one of these out
+ * again, which is how `observability/widgets/log-detail` came to format its own timestamp, pick its own
+ * tag colour and stringify its own JSON for nine values the table beside it already knew how to draw.
+ * Two implementations of `datetime` are two answers to when something happened.
+ */
+export type PhiRenderedValueDefinition = {
+    renderer?: PhiTableValueRenderer;
+    /** What a stored value is called when it is shown -- a status code as a word. */
+    valueMap?: Readonly<Record<string, string>>;
+    tagColorMap?: Readonly<Record<string, PhiTableTagColor>>;
+    tagVariant?: PhiTableTagVariant;
+};
+/**
+ * Where the value stands, which only `json` cares about.
+ *
+ * A `cell` shares its line with a dozen others and gets one line, so an object is stringified flat. A
+ * `block` has the width of a record to itself, so the same object is indented and wrapped -- which is
+ * what the log detail wrote by hand as `JSON.stringify(meta, null, 2)` inside a `<pre>`, and the reason
+ * 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

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { formatPhiDate, formatPhiDateTime } from "../../../../helpers/format-date-time";
+import { usePhiIntlLocale } from "../../../root/phi-intl-locale";
+import { PhiFlexControl } from "../../../controls/phi-flex-control";
+import { PhiTagControl } from "../../../controls/phi-tag-control";
+import { PhiTypographyControl } from "../../../controls/phi-typography-control";
+import { PhiLink } from "../../../navigation/phi-link";
+import { PhiIcon } from "../../../shell/phi-icon";
+import { isPhiRecord } from "../../../../helpers/is-record";
+/**
+ * **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 function normalizePhiRenderedText(value) {
+    if (value == null)
+        return "";
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(normalizePhiRenderedText).filter(Boolean).join(", ");
+    return isPhiRecord(value) ? JSON.stringify(value) : "";
+}
+function resolveTagColor(color) {
+    return typeof color === "object" ? color.value : color;
+}
+/** A component rather than a call, because the page's locale is read from context. */
+function PhiRenderedDate({ value, withTime }) {
+    const locale = usePhiIntlLocale();
+    return withTime ? formatPhiDateTime(value, locale) : formatPhiDate(value, locale);
+}
+export function renderPhiValueContent(value, definition, presentation = "cell") {
+    if (value == null || value === "")
+        return null;
+    const normalizedValue = normalizePhiRenderedText(value);
+    const displayValue = definition.valueMap?.[normalizedValue] ?? normalizedValue;
+    if (definition.renderer === "email" || definition.renderer === "link") {
+        const href = String(value);
+        return _jsx(PhiLink, { href: definition.renderer === "email" ? `mailto:${href}` : href, children: displayValue });
+    }
+    if (definition.renderer === "tags") {
+        const values = Array.isArray(value) ? value : [value];
+        return (_jsx(PhiFlexControl, { align: "center", gap: 4, wrap: true, style: { display: "inline-flex" }, children: values.map((entry, index) => {
+                const normalizedEntry = normalizePhiRenderedText(entry);
+                return (_jsx(PhiTagControl, { color: resolveTagColor(definition.tagColorMap?.[normalizedEntry]), variant: definition.tagVariant ?? "outlined", children: definition.valueMap?.[normalizedEntry] ?? normalizedEntry }, `${normalizedEntry}:${index}`));
+            }) }));
+    }
+    if (definition.renderer === "date" || definition.renderer === "datetime") {
+        return _jsx(PhiRenderedDate, { value: normalizedValue, withTime: definition.renderer === "datetime" });
+    }
+    if (definition.renderer === "json" && presentation === "block") {
+        return (_jsx(PhiTypographyControl, { code: true, style: { display: "block", whiteSpace: "pre-wrap" }, children: JSON.stringify(value, null, 2) }));
+    }
+    if (definition.renderer === "json" || definition.renderer === "code") {
+        return _jsx(PhiTypographyControl, { code: true, children: displayValue });
+    }
+    if (definition.renderer === "badge") {
+        return (_jsx(PhiTagControl, { color: resolveTagColor(definition.tagColorMap?.[normalizedValue]), variant: definition.tagVariant ?? "outlined", children: displayValue }));
+    }
+    if (definition.renderer === "switch" || definition.renderer === "checkbox") {
+        return _jsx(PhiIcon, { name: value === true ? "check" : "close" });
+    }
+    if (definition.renderer === "icon")
+        return typeof value === "string" && value.trim() ? _jsx(PhiIcon, { name: value }) : null;
+    return displayValue;
+}

package/components/widgets/client/shared/phi-search-draft.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The query a search draft stands for.
+ *
+ * Trimmed, and empty below the minimum length rather than absent: a person who shortens "chair" to "ch"
+ * has taken the search back, and the results have to follow them there. Emitting nothing kept the list
+ * filtered by a word that was no longer in the box.
+ */
+export declare function resolvePhiSearchDraftQuery(draft: string, minQueryLength: number): string;
+export type PhiSearchDraft = {
+    /** What the box shows. */
+    draft: string;
+    setDraft: (draft: string) => void;
+    /**
+     * Takes the current draft as answered without emitting it -- for a submit that delivers the query
+     * another way, so the debounce does not repeat it as a change afterwards.
+     */
+    settle: () => void;
+};
+/**
+ * Typing is not a query: the draft is what a person sees, the query follows once they stop.
+ *
+ * Three things hold between the two. The draft follows the query when it changes from outside -- a
+ * reset, a new source -- but not when the change is this draft's own echo, which would eat a trailing
+ * space the query trimmed away. The debounce restarts only when the draft does; the callback is read
+ * when the timer fires, so a parent that renders with a new closure does not postpone the search. And
+ * an empty box answers at once, because there is nothing left to wait for.
+ */
+export declare function usePhiSearchDraft({ query, onQueryChange, debounceMs, minQueryLength, }: {
+    query: string;
+    onQueryChange: (query: string) => void;
+    debounceMs: number;
+    minQueryLength?: number;
+}): PhiSearchDraft;

package/components/widgets/client/shared/phi-search-draft.js

@@ -0,0 +1,52 @@
+"use client";
+import { useCallback, useEffect, useEffectEvent, useState } from "react";
+/**
+ * The query a search draft stands for.
+ *
+ * Trimmed, and empty below the minimum length rather than absent: a person who shortens "chair" to "ch"
+ * has taken the search back, and the results have to follow them there. Emitting nothing kept the list
+ * filtered by a word that was no longer in the box.
+ */
+export function resolvePhiSearchDraftQuery(draft, minQueryLength) {
+    const trimmed = draft.trim();
+    return trimmed.length < Math.max(1, minQueryLength) ? "" : trimmed;
+}
+/**
+ * Typing is not a query: the draft is what a person sees, the query follows once they stop.
+ *
+ * Three things hold between the two. The draft follows the query when it changes from outside -- a
+ * reset, a new source -- but not when the change is this draft's own echo, which would eat a trailing
+ * space the query trimmed away. The debounce restarts only when the draft does; the callback is read
+ * when the timer fires, so a parent that renders with a new closure does not postpone the search. And
+ * an empty box answers at once, because there is nothing left to wait for.
+ */
+export function usePhiSearchDraft({ query, onQueryChange, debounceMs, minQueryLength = 1, }) {
+    const [draft, setDraft] = useState(query);
+    // The query as last seen from outside, to tell a change of it from a render that repeats it.
+    const [seenQuery, setSeenQuery] = useState(query);
+    // The query this draft last stood for: emitted by it, settled by it, or taken over from outside.
+    const [answeredQuery, setAnsweredQuery] = useState(() => resolvePhiSearchDraftQuery(query, minQueryLength));
+    if (query !== seenQuery) {
+        setSeenQuery(query);
+        const externalQuery = resolvePhiSearchDraftQuery(query, minQueryLength);
+        if (externalQuery !== answeredQuery) {
+            setAnsweredQuery(externalQuery);
+            setDraft(query);
+        }
+    }
+    const emit = useEffectEvent((nextQuery) => {
+        setAnsweredQuery(nextQuery);
+        onQueryChange(nextQuery);
+    });
+    const nextQuery = resolvePhiSearchDraftQuery(draft, minQueryLength);
+    const delayMs = draft.trim() === "" ? 0 : Math.max(0, debounceMs);
+    useEffect(() => {
+        if (nextQuery === answeredQuery) {
+            return;
+        }
+        const timer = window.setTimeout(() => emit(nextQuery), delayMs);
+        return () => window.clearTimeout(timer);
+    }, [answeredQuery, delayMs, nextQuery]);
+    const settle = useCallback(() => setAnsweredQuery(nextQuery), [nextQuery]);
+    return { draft, setDraft, settle };
+}

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

@@ -1,10 +1,21 @@
 import type { PhiRuntimeDataProviderKey } from "../../../../types/runtime-data-provider";
-import { type PhiTableProviderMutationRequest, type PhiTableProviderMutationResult, type PhiTableProviderQueryRequest, type PhiTableProviderResourceDescriptor } from "../../../../types/table-widget";
+import { type PhiTableProviderMutationRequest, type PhiTableProviderRecordRequest, 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

@@ -4,10 +4,21 @@ function readValue(row, path) {
         ? current[segment]
         : undefined, row);
 }
-function compareValues(left, right) {
-    if (typeof left === "number" && typeof right === "number")
-        return left - right;
-    return String(left ?? "").localeCompare(String(right ?? ""));
+/*
+ * 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
+ * string. An empty cell is not the empty string -- it has no place in the order, so it goes after
+ * every value in both directions rather than first in one of them.
+ */
+function compareSortValues(left, right, direction) {
+    const leftEmpty = left == null || left === "";
+    const rightEmpty = right == null || right === "";
+    if (leftEmpty || rightEmpty)
+        return leftEmpty === rightEmpty ? 0 : leftEmpty ? 1 : -1;
+    const comparison = typeof left === "number" && typeof right === "number"
+        ? left - right
+        : String(left).localeCompare(String(right), undefined, { numeric: true });
+    return direction === "descending" ? -comparison : comparison;
 }
 function matchesFilter(value, filter) {
     if (filter == null || filter === "" || (Array.isArray(filter) && filter.length === 0))
@@ -83,6 +94,25 @@ function orderHierarchyRows(rows, resource) {
         append(row);
     return ordered;
 }
+/**
+ * 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 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));
+    if (!row) {
+        throw new PhiTableProviderError("row-not-found", `Static Table resource "${request.resourceKey}" has no row "${identity}".`);
+    }
+    return { ...row };
+}
 export function queryPhiStaticTableResource(resource, request) {
     let rows = [...resource.rows];
     const search = request.query.search?.trim().toLocaleLowerCase();
@@ -106,9 +136,9 @@ export function queryPhiStaticTableResource(resource, request) {
     if (request.query.sorts?.length) {
         rows.sort((left, right) => {
             for (const sort of request.query.sorts ?? []) {
-                const comparison = compareValues(readValue(left, sort.key), readValue(right, sort.key));
+                const comparison = compareSortValues(readValue(left, sort.key), readValue(right, sort.key), sort.direction);
                 if (comparison !== 0)
-                    return sort.direction === "descending" ? -comparison : comparison;
+                    return comparison;
             }
             return 0;
         });
@@ -118,7 +148,10 @@ export function queryPhiStaticTableResource(resource, request) {
     const pageSize = request.query.pageSize && request.query.pageSize > 0
         ? request.query.pageSize
         : total || 1;
-    const page = request.query.page && request.query.page > 0 ? request.query.page : 1;
+    const requestedPage = request.query.page && request.query.page > 0 ? request.query.page : 1;
+    // A page past the end -- the rows shrank under a filter, or one was deleted -- answers with the last
+    // page, and says so, rather than an empty page the pager cannot explain.
+    const page = Math.min(requestedPage, Math.max(1, Math.ceil(total / pageSize)));
     return {
         rows: rows.slice((page - 1) * pageSize, page * pageSize),
         total,
@@ -137,6 +170,13 @@ export function createPhiStaticTableProviderRegistration({ key, resources, }) {
             }
             return queryPhiStaticTableResource(resource, request);
         },
+        readRecord: async (request) => {
+            const resource = resources.find((candidate) => candidate.descriptor.resourceKey === request.resourceKey);
+            if (!resource) {
+                throw new PhiTableProviderError("resource-not-found", `Unknown static Table resource "${request.resourceKey}".`);
+            }
+            return readPhiStaticTableRecord(resource, request);
+        },
     };
 }
 export function createPhiVersionedStaticTableProviderRegistration({ key, resources, mode, store, }) {
@@ -160,6 +200,16 @@ export function createPhiVersionedStaticTableProviderRegistration({ key, resourc
             });
             return queryPhiStaticTableResource({ descriptor, rows: snapshot.rows }, request);
         },
+        readRecord: async (request) => {
+            const descriptor = findResource(request.resourceKey);
+            const snapshot = await store.read({
+                resourceKey: request.resourceKey,
+                status: mode === "authoring" ? "draft" : "published",
+                params: request.params,
+                signal: request.signal,
+            });
+            return readPhiStaticTableRecord({ descriptor, rows: snapshot.rows }, request);
+        },
         ...(mode === "authoring"
             ? {
                 mutate: async (request) => {

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

@@ -0,0 +1,14 @@
+export type ReadPhiTableProviderResponseOptions = {
+    /** Who was asked, for the sentence a refusal without one of its own gets: "Groups request failed". */
+    subject: string;
+    /** Which body keys carry the refusal, in order. Default `error`. */
+    errorKeys?: readonly string[];
+};
+/**
+ * A Table Provider's answer from its route, or the `request-failed` error the Table shows for it.
+ *
+ * Five Providers carried this reader word for word apart from the subject in the fallback sentence
+ * and whether `message` is read before `error`. A Table Provider fails in its own vocabulary
+ * (`PhiTableProviderError`), which is why this is not the plain `readPhiJsonError`.
+ */
+export declare function readPhiTableProviderResponse<T>(response: Response, { subject, errorKeys }: ReadPhiTableProviderResponseOptions): Promise<T | null>;

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

@@ -0,0 +1,16 @@
+import { readPhiJsonError, readPhiJsonPayload } from "../../../../helpers/client-json-request";
+import { PhiTableProviderError } from "../../../../types/table-widget";
+/**
+ * A Table Provider's answer from its route, or the `request-failed` error the Table shows for it.
+ *
+ * Five Providers carried this reader word for word apart from the subject in the fallback sentence
+ * and whether `message` is read before `error`. A Table Provider fails in its own vocabulary
+ * (`PhiTableProviderError`), which is why this is not the plain `readPhiJsonError`.
+ */
+export async function readPhiTableProviderResponse(response, { subject, errorKeys }) {
+    const payload = await readPhiJsonPayload(response);
+    if (!response.ok) {
+        throw new PhiTableProviderError("request-failed", readPhiJsonError(payload, `${subject} request failed with status ${response.status}.`, errorKeys));
+    }
+    return payload;
+}