@phis/ui 0.2.1 → 0.4.0

package/components/shell/phi-cms-shell.js

@@ -44,7 +44,8 @@ function PhiShellChromePane({ family, stickyTop, }) {
             ? { ...PHI_SHELL_CHROME_PANE_PAINT, boxShadow }
             : { ...PHI_SHELL_CHROME_PANE_PAINT, boxShadow, position: "sticky", top: stickyTop } }));
 }
-export function PhiCmsShell({ content, headerTop, headerMain, headerBottom, hero, siderLeft, siderRight, siderLeftFullHeight = false, footerTop, footerMain, footerBottom, drawer, headerPaneStickyTop, }) {
+export function PhiCmsShell({ content, headerTop, headerMain, headerBottom, hero, siderLeft, siderRight, siderLeftFullHeight = false, footerTop, footerMain, footerBottom, drawer, headerPaneStickyTop, headerTopRoom, }) {
+    const roomStyle = headerTopRoom;
     const hasLeftFullHeightSidebar = siderLeftFullHeight && Boolean(siderLeft);
     const shellVariant = hasLeftFullHeightSidebar
         ? "full-height-sider"
@@ -59,7 +60,7 @@ export function PhiCmsShell({ content, headerTop, headerMain, headerBottom, hero
     const hasHeader = Boolean(headerTop || headerMain || headerBottom);
     const hasFooter = Boolean(footerTop || footerMain || footerBottom);
     if (hasLeftFullHeightSidebar) {
-        return (_jsxs("div", { className: "shell-sider-full", "data-phi-shell-layout": "cms", "data-phi-shell-variant": shellVariant, "data-phi-shell-chrome-panes": "true", children: [hasHeader ? _jsx(PhiShellChromePane, { family: "header", stickyTop: headerPaneStickyTop }) : null, _jsx(PhiShellChromePane, { family: "sider" }), siderRight ? _jsx(PhiShellChromePane, { family: "sider-right" }) : null, hasFooter ? _jsx(PhiShellChromePane, { family: "footer" }) : null, siderLeft, headerTop, headerMain, headerBottom, hero, _jsx("main", { className: "content phi-shell-content-main", children: content }), siderRight, footerTop, footerMain, footerBottom, drawer] }));
+        return (_jsxs("div", { className: "shell-sider-full", "data-phi-shell-layout": "cms", "data-phi-shell-variant": shellVariant, "data-phi-shell-chrome-panes": "true", style: roomStyle, children: [hasHeader ? _jsx(PhiShellChromePane, { family: "header", stickyTop: headerPaneStickyTop }) : null, _jsx(PhiShellChromePane, { family: "sider" }), siderRight ? _jsx(PhiShellChromePane, { family: "sider-right" }) : null, hasFooter ? _jsx(PhiShellChromePane, { family: "footer" }) : null, siderLeft, headerTop, headerMain, headerBottom, hero, _jsx("main", { className: "content phi-shell-content-main", children: content }), siderRight, footerTop, footerMain, footerBottom, drawer] }));
     }
-    return (_jsxs("div", { className: siderLeft ? "shell-sider-embedded" : "shell-sider-embedded shell-sider-embedded--no-sider", "data-phi-shell-layout": "cms", "data-phi-shell-variant": shellVariant, "data-phi-shell-chrome-panes": "true", children: [headerTop || headerMain ? _jsx(PhiShellChromePane, { family: "header", stickyTop: headerPaneStickyTop }) : null, headerBottom ? _jsx(PhiShellChromePane, { family: "header-bottom" }) : null, siderLeft ? _jsx(PhiShellChromePane, { family: "sider" }) : null, siderRight ? _jsx(PhiShellChromePane, { family: "sider-right" }) : null, hasFooter ? _jsx(PhiShellChromePane, { family: "footer" }) : null, headerTop, headerMain, headerBottom, hero, siderLeft, _jsx("main", { className: "content phi-shell-content-main", children: content }), siderRight, footerTop, footerMain, footerBottom, drawer] }));
+    return (_jsxs("div", { className: siderLeft ? "shell-sider-embedded" : "shell-sider-embedded shell-sider-embedded--no-sider", "data-phi-shell-layout": "cms", "data-phi-shell-variant": shellVariant, "data-phi-shell-chrome-panes": "true", style: roomStyle, children: [headerTop || headerMain ? _jsx(PhiShellChromePane, { family: "header", stickyTop: headerPaneStickyTop }) : null, headerBottom ? _jsx(PhiShellChromePane, { family: "header-bottom" }) : null, siderLeft ? _jsx(PhiShellChromePane, { family: "sider" }) : null, siderRight ? _jsx(PhiShellChromePane, { family: "sider-right" }) : null, hasFooter ? _jsx(PhiShellChromePane, { family: "footer" }) : null, headerTop, headerMain, headerBottom, hero, siderLeft, _jsx("main", { className: "content phi-shell-content-main", children: content }), siderRight, footerTop, footerMain, footerBottom, drawer] }));
 }

package/components/shell/phi-icon.d.ts

@@ -1,6 +1,11 @@
+import { type PhiAntdIconPresentation } from "./phi-antd-icon";
+/**
+ * `style`, `className`, `title`, `ariaLabel` and `twoToneColor` reach the Ant Design icons, which is
+ * where the house draws its interface icons; a motif, Iconify or asset icon takes its size only.
+ */
 type PhiIconProps = {
     name?: string;
     size?: number | string;
-};
-export declare function PhiIcon({ name, size }: PhiIconProps): import("react").JSX.Element | null;
+} & PhiAntdIconPresentation;
+export declare function PhiIcon({ name, size, ...presentation }: PhiIconProps): import("react").JSX.Element | null;
 export {};

package/components/shell/phi-icon.js

@@ -26,9 +26,9 @@ function renderIconFallback(size) {
             height: size,
         } }));
 }
-function renderAntdIcon(key, size) {
+function renderAntdIcon(key, size, presentation) {
     const icon = PHI_ANTD_ICON_NAMES[key];
-    return icon ? _jsx(PhiAntdIcon, { icon: icon, size: size }) : null;
+    return icon ? _jsx(PhiAntdIcon, { icon: icon, size: size, ...presentation }) : null;
 }
 function renderBuilderIcon(namespace, motif, size) {
     const isLayoutNamespace = namespace.endsWith("/layouts");
@@ -68,7 +68,7 @@ function PhiIconifyIcon({ icon, size }) {
     }
     return _jsx(IconifyIcon, { icon: icon, width: size, height: size, inline: true });
 }
-export function PhiIcon({ name, size = 16 }) {
+export function PhiIcon({ name, size = 16, ...presentation }) {
     if (!name) {
         return null;
     }
@@ -76,7 +76,7 @@ export function PhiIcon({ name, size = 16 }) {
     const [namespace, ...rest] = name.split(":");
     const value = rest.join(":");
     if (!value) {
-        return renderAntdIcon(name, resolvedSize);
+        return renderAntdIcon(name, resolvedSize, presentation);
     }
     const builderIcon = renderBuilderIcon(namespace, value, resolvedSize);
     if (builderIcon) {
@@ -84,7 +84,7 @@ export function PhiIcon({ name, size = 16 }) {
     }
     switch (namespace) {
         case "antd":
-            return renderAntdIcon(value, resolvedSize);
+            return renderAntdIcon(value, resolvedSize, presentation);
         case "iconify":
             return value ? _jsx(PhiIconifyIcon, { icon: value, size: resolvedSize }) : null;
         case "asset":

package/components/shell/phi-locale-switch.js

@@ -1,10 +1,11 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import Link from "next/link";
-import { usePathname, useSearchParams } from "next/navigation";
+import { useSearchParams } from "next/navigation";
 import { isKnownSpecialCmsRoot } from "../../helpers/cms-routing";
 import { localizeAreaPath, stripLocaleAndAreaFromPathname } from "../../helpers/locale";
 import { PhiPillDropdownControl } from "../controls/phi-dropdown-control";
+import { usePhiPathname } from "../runtime/use-phi-pathname";
 /**
  * Remembers the locale a viewer picked, for every page that carries no locale of its own.
  *
@@ -20,7 +21,7 @@ function rememberPhiLocaleChoice(locale) {
         `phis_locale=${encodeURIComponent(locale)}; Path=/; Max-Age=31536000; SameSite=Lax${secure}`;
 }
 export function PhiLocaleSwitch({ currentLocale, localeOptions, mode = "label-list", showText = true, interactive = true, }) {
-    const pathname = usePathname() ?? "/";
+    const pathname = usePhiPathname();
     const searchParams = useSearchParams();
     const currentQuery = searchParams?.toString();
     const pathSegments = pathname.split("/").filter(Boolean);

package/components/shell/phi-widget-icon.js

@@ -1,34 +1,34 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { ApiOutlined, AppstoreOutlined, BranchesOutlined, ClusterOutlined, CodeOutlined, CustomerServiceOutlined, DashboardOutlined, EditOutlined, FileTextOutlined, HistoryOutlined, LayoutOutlined, MenuOutlined, MessageOutlined, MonitorOutlined, PictureOutlined, ReadOutlined, SettingOutlined, ShoppingOutlined, SkinOutlined, TeamOutlined, TranslationOutlined, UserOutlined, } from "@ant-design/icons";
+import { PhiIcon } from "./phi-icon";
 const WIDGET_ICON_REGISTRY = {
-    layout: LayoutOutlined,
-    content: AppstoreOutlined,
-    basic: FileTextOutlined,
-    navigation: MenuOutlined,
-    form: ReadOutlined,
-    forms: ReadOutlined,
-    commerce: ShoppingOutlined,
-    auth: UserOutlined,
-    admin: SettingOutlined,
-    builder: BranchesOutlined,
-    dashboard: DashboardOutlined,
-    developer: CodeOutlined,
-    editor: EditOutlined,
-    groups: ClusterOutlined,
-    internal: BranchesOutlined,
-    localization: TranslationOutlined,
-    media: PictureOutlined,
-    observability: MonitorOutlined,
-    revisions: HistoryOutlined,
-    runtime: ApiOutlined,
-    support: CustomerServiceOutlined,
-    threads: MessageOutlined,
-    "user-management": TeamOutlined,
-    brand: SkinOutlined,
-    theme: SkinOutlined,
+    layout: "layout",
+    content: "appstore",
+    basic: "file",
+    navigation: "menu",
+    form: "form",
+    forms: "form",
+    commerce: "shopping",
+    auth: "user",
+    admin: "setting",
+    builder: "branches",
+    dashboard: "dashboard",
+    developer: "code",
+    editor: "edit",
+    groups: "cluster",
+    internal: "branches",
+    localization: "translation",
+    media: "picture",
+    observability: "monitor",
+    revisions: "history",
+    runtime: "api",
+    support: "customer-service",
+    threads: "message",
+    "user-management": "team",
+    brand: "skin",
+    theme: "skin",
 };
 export function PhiWidgetIcon({ family, size = 16 }) {
-    const Icon = WIDGET_ICON_REGISTRY[family];
-    return Icon ? _jsx(Icon, { style: { fontSize: size } }) : null;
+    const name = WIDGET_ICON_REGISTRY[family];
+    return name ? _jsx(PhiIcon, { name: name, size: size }) : null;
 }

package/components/state/history-store.d.ts

@@ -1,5 +1,13 @@
-export type PhiHistoryEntry<TSnapshot> = {
-    label: string;
+/**
+ * One step a history can take back.
+ *
+ * `action` says what the step was, in the terms of whoever recorded it -- a Builder edit names its kind
+ * and the node it touched, a Theme edit the part of the Theme it changed. It is data rather than a
+ * sentence because the sentence belongs to the reader: the undo message and the button's tooltip are
+ * written in the visitor's language at the moment they are shown, from the Label Set that reader holds.
+ */
+type PhiHistoryEntry<TSnapshot, TAction> = {
+    action: TAction;
     before: TSnapshot;
     after: TSnapshot;
     /**
@@ -13,23 +21,27 @@ export type PhiHistoryEntry<TSnapshot> = {
      */
     coalesceKey?: string;
 };
-export declare function createPhiHistoryStore<TSnapshot>(storeId: string, options?: {
+/** What can be taken back and brought back next, as the toolbar shows it. */
+type PhiHistoryAvailability<TAction> = {
+    canUndo: boolean;
+    canRedo: boolean;
+    /** The step an undo would take back, or null. */
+    undoAction: TAction | null;
+    /** The step a redo would bring back, or null. */
+    redoAction: TAction | null;
+};
+export declare function createPhiHistoryStore<TSnapshot, TAction>(storeId: string, options?: {
     limit?: number;
 }): {
     clear: (scopeKey: string) => void;
     endGesture: (scopeKey?: string) => void;
-    getAvailability: (scopeKey: string) => {
-        canUndo: boolean;
-        canRedo: boolean;
-    };
-    getHead: (scopeKey: string) => PhiHistoryEntry<TSnapshot> | null;
-    record: (scopeKey: string, entry: PhiHistoryEntry<TSnapshot>) => void;
-    redo: (scopeKey: string, apply: (snapshot: TSnapshot) => void) => boolean;
+    getAvailability: (scopeKey: string) => PhiHistoryAvailability<TAction>;
+    getHead: (scopeKey: string) => PhiHistoryEntry<TSnapshot, TAction> | null;
+    record: (scopeKey: string, entry: PhiHistoryEntry<TSnapshot, TAction>) => void;
+    redo: (scopeKey: string, apply: (snapshot: TSnapshot) => void) => PhiHistoryEntry<TSnapshot, TAction> | null;
     subscribe: (scopeKey: import("./plugin-state-store").PhiPluginStateScope, listener: () => void) => () => void;
-    undo: (scopeKey: string, apply: (snapshot: TSnapshot) => void) => boolean;
-    useAvailability: (scopeKey: string) => {
-        canUndo: boolean;
-        canRedo: boolean;
-    };
-    useHead: (scopeKey: string) => PhiHistoryEntry<TSnapshot> | null;
+    undo: (scopeKey: string, apply: (snapshot: TSnapshot) => void) => PhiHistoryEntry<TSnapshot, TAction> | null;
+    useAvailability: (scopeKey: string) => PhiHistoryAvailability<TAction>;
+    useHead: (scopeKey: string) => PhiHistoryEntry<TSnapshot, TAction> | null;
 };
+export {};

package/components/state/history-store.js

@@ -27,33 +27,35 @@ export function createPhiHistoryStore(storeId, options) {
             };
         });
     }
+    /** Takes the newest step back and answers with it, so the caller can say what it took back. */
     function undo(scopeKey, apply) {
         openGestures.delete(scopeKey);
         const current = store.getSnapshot(scopeKey);
         const entry = current.past.at(-1);
         if (!entry) {
-            return false;
+            return null;
         }
         apply(entry.before);
         store.replace(scopeKey, {
             past: current.past.slice(0, -1),
             future: [...current.future, entry],
         });
-        return true;
+        return entry;
     }
+    /** Brings the last step taken back again and answers with it. */
     function redo(scopeKey, apply) {
         openGestures.delete(scopeKey);
         const current = store.getSnapshot(scopeKey);
         const entry = current.future.at(-1);
         if (!entry) {
-            return false;
+            return null;
         }
         apply(entry.after);
         store.replace(scopeKey, {
             past: [...current.past, entry],
             future: current.future.slice(0, -1),
         });
-        return true;
+        return entry;
     }
     /**
      * Ends whatever gesture is still open, so the next record starts an entry of its own. Called when the
@@ -75,6 +77,8 @@ export function createPhiHistoryStore(storeId, options) {
         return {
             canUndo: state.past.length > 0,
             canRedo: state.future.length > 0,
+            undoAction: state.past.at(-1)?.action ?? null,
+            redoAction: state.future.at(-1)?.action ?? null,
         };
     }
     /**
@@ -93,6 +97,8 @@ export function createPhiHistoryStore(storeId, options) {
         return {
             canUndo: state.past.length > 0,
             canRedo: state.future.length > 0,
+            undoAction: state.past.at(-1)?.action ?? null,
+            redoAction: state.future.at(-1)?.action ?? null,
         };
     }
     return {

package/components/surface/phi-surface-ground.d.ts

@@ -0,0 +1,16 @@
+import type { PhiSurfaceGround } from "../../helpers/surface-style";
+/**
+ * Where the paint lies when it is larger than the box: one picture across several boxes, each showing
+ * its own part of it. `left` and `width` in CSS lengths relative to the box; the box clips the rest.
+ */
+export type PhiSurfaceGroundFrame = {
+    left: string;
+    width: string;
+};
+export declare function PhiSurfaceGroundLayer({ ground, className, frame, }: {
+    ground: PhiSurfaceGround | null | undefined;
+    /** For a caller that moves the paint itself, a hover zoom for one. */
+    className?: string;
+    /** The paint's own extent, where it reaches past the box (the Split Card's two cards). */
+    frame?: PhiSurfaceGroundFrame;
+}): import("react").JSX.Element | null;

package/components/surface/phi-surface-ground.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PHI_BACKGROUND_BLUR_RADIUS_PX } from "../widgets/config/background";
+import { PhiBackgroundMotionLayer } from "../cms/clients/phi-background-motion-layer-lazy";
+/**
+ * The layer a Surface's paint lives on when the box cannot carry it (see `PhiSurfaceGround`).
+ *
+ * Rendered as the box's first child, behind the content at `z-index: -1`, clipped to the box and its
+ * corners. A still paint is rendered on the server like any other markup -- a softened picture must not
+ * arrive sharp and blur after hydration -- and only a moving one hands over to the motion layer, which
+ * carries the same softening.
+ *
+ * No hooks and no Client boundary of its own, so a Server Component and a Client Component render it
+ * alike.
+ */
+const PHI_SURFACE_GROUND_HOST = {
+    position: "absolute",
+    inset: 0,
+    overflow: "hidden",
+    borderRadius: "inherit",
+    pointerEvents: "none",
+    zIndex: -1,
+};
+/*
+ * A blurred paint fades towards its own edges, so the layer reaches past the box by twice the radius and
+ * the box clips it: what shows is softened all the way to the corner instead of thinning at the rim.
+ */
+const PHI_SURFACE_GROUND_BLEED = `${-2 * PHI_BACKGROUND_BLUR_RADIUS_PX}px`;
+function resolvePhiSurfaceGroundPaintBox(bleeds, frame) {
+    const edge = bleeds ? PHI_SURFACE_GROUND_BLEED : "0px";
+    if (!frame) {
+        return { top: edge, right: edge, bottom: edge, left: edge };
+    }
+    return {
+        top: edge,
+        bottom: edge,
+        left: bleeds ? `calc(${frame.left} + ${PHI_SURFACE_GROUND_BLEED})` : frame.left,
+        width: bleeds ? `calc(${frame.width} - 2 * ${PHI_SURFACE_GROUND_BLEED})` : frame.width,
+    };
+}
+export function PhiSurfaceGroundLayer({ ground, className, frame, }) {
+    if (!ground) {
+        return null;
+    }
+    if (ground.motion) {
+        return _jsx(PhiBackgroundMotionLayer, { config: ground.motion });
+    }
+    return (_jsx("div", { "aria-hidden": "true", "data-phi-surface-ground": "true", style: PHI_SURFACE_GROUND_HOST, children: _jsx("div", { className: className, "data-phi-surface-ground-paint": "true", style: {
+                ...ground.paint,
+                position: "absolute",
+                // Longhands only: React refuses a shorthand beside the longhands a frame sets on a rerender.
+                ...resolvePhiSurfaceGroundPaintBox(ground.filter != null, frame),
+                ...(ground.filter ? { filter: ground.filter } : {}),
+            } }) }));
+}

package/components/surface/phi-surface-tone-scope.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+import type { PhiThemeToneSource } from "../root/phi-theme-tone-source";
+import type { PhiThemeMode } from "../../theme/phi-theme-presets";
+/**
+ * The other mode, around a Surface's content -- the heavy half of a tone, loaded only where a Surface
+ * asks for a mode its content is not in. The Theme comes from the root, which resolved both modes; its
+ * variables are written under `cssVarKey`, the class the Surface's box carries (`phi-tone-*`).
+ */
+export declare function PhiSurfaceToneScope({ mode, cssVarKey, source, children, }: {
+    mode: PhiThemeMode;
+    cssVarKey: string;
+    source: PhiThemeToneSource;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/components/surface/phi-surface-tone-scope.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { PhiNestedModeConfigProvider } from "../root/phi-config-provider";
+/**
+ * The other mode, around a Surface's content -- the heavy half of a tone, loaded only where a Surface
+ * asks for a mode its content is not in. The Theme comes from the root, which resolved both modes; its
+ * variables are written under `cssVarKey`, the class the Surface's box carries (`phi-tone-*`).
+ */
+export function PhiSurfaceToneScope({ mode, cssVarKey, source, children, }) {
+    return (_jsx(PhiNestedModeConfigProvider, { mode: mode, theme: source.themes[mode], cssVarKey: cssVarKey, locale: source.locale, customColors: source.customColorsByMode[mode], children: children }));
+}

package/components/surface/phi-surface-tone.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import type { PhiThemeMode } from "../../theme/phi-theme-presets";
+import { type PhiSurfaceTone as PhiSurfaceToneValue } from "../../types/surface";
+/** The mode a tone asks for: `inverse` is the other mode than the page's. */
+export declare function resolvePhiSurfaceToneMode(tone: PhiSurfaceToneValue, pageMode: PhiThemeMode): PhiThemeMode | null;
+/**
+ * A Surface's content in the mode its `tone` asks for.
+ *
+ * Rendered inside the box, around its content; the box itself carries the tone's class
+ * (`resolvePhiSurfaceToneClassName`), and that class is where the other mode's variables are written. When
+ * the content is already in that mode -- the page is, or a Surface around it is -- nothing is mounted: the
+ * class then has no variables of its own and the content inherits the right ones. Otherwise the scope is
+ * loaded on its own, rendered on the server like everything else, and only where a page uses it.
+ */
+export declare function PhiSurfaceTone({ tone, children, }: {
+    tone: PhiSurfaceToneValue | null | undefined;
+    children: ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;

package/components/surface/phi-surface-tone.js

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { lazy, Suspense } from "react";
+import { usePhiConfig } from "../root/phi-config-provider";
+import { usePhiThemeToneSource } from "../root/phi-theme-tone-source";
+import { resolvePhiSurfaceToneClassName } from "../../types/surface";
+const PhiSurfaceToneScope = lazy(async () => ({
+    default: (await import("./phi-surface-tone-scope")).PhiSurfaceToneScope,
+}));
+/** The mode a tone asks for: `inverse` is the other mode than the page's. */
+export function resolvePhiSurfaceToneMode(tone, pageMode) {
+    if (tone === "light" || tone === "dark")
+        return tone;
+    if (tone === "inverse")
+        return pageMode === "dark" ? "light" : "dark";
+    return null;
+}
+/**
+ * A Surface's content in the mode its `tone` asks for.
+ *
+ * Rendered inside the box, around its content; the box itself carries the tone's class
+ * (`resolvePhiSurfaceToneClassName`), and that class is where the other mode's variables are written. When
+ * the content is already in that mode -- the page is, or a Surface around it is -- nothing is mounted: the
+ * class then has no variables of its own and the content inherits the right ones. Otherwise the scope is
+ * loaded on its own, rendered on the server like everything else, and only where a page uses it.
+ */
+export function PhiSurfaceTone({ tone, children, }) {
+    const { mode } = usePhiConfig();
+    const source = usePhiThemeToneSource();
+    const cssVarKey = resolvePhiSurfaceToneClassName(tone);
+    const target = tone && source ? resolvePhiSurfaceToneMode(tone, source.pageMode) : null;
+    if (!target || !source || !cssVarKey || target === mode) {
+        return children;
+    }
+    return (_jsx(Suspense, { fallback: null, children: _jsx(PhiSurfaceToneScope, { mode: target, cssVarKey: cssVarKey, source: source, children: children }) }));
+}

package/components/tables/client/phi-table-binding.d.ts

@@ -1,4 +1,4 @@
-import type { PhiTableProviderActionMutationRequest, PhiTableProviderDropMutationRequest, PhiTableProviderFieldMutationRequest, PhiTableProviderMutationRequest, PhiTableProviderMutationResult, PhiTableProviderQueryResult, PhiTableProviderResourceDescriptor, PhiTableProviderRowMoveMutationRequest, PhiTableProviderRowPatchMutationRequest, PhiTableQuery, PhiTableRowIdentity, PhiTableSummaryValue } from "../../../types/table-widget";
+import type { PhiTableProviderActionMutationRequest, PhiTableProviderDropMutationRequest, PhiTableProviderFieldMutationRequest, PhiTableProviderMutationRequest, PhiTableProviderMutationResult, PhiTableProviderQueryResult, PhiTableProviderResourceDescriptor, PhiTableProviderRowMoveMutationRequest, PhiTableProviderRowPatchMutationRequest, PhiTableQuery, PhiTableQueryValue, PhiTableRowIdentity, PhiTableSummaryValue } from "../../../types/table-widget";
 import type { PhiProviderResourceSource } from "../../../types/runtime-data-provider";
 import { PhiTableProviderError } from "../../../types/table-widget";
 type TableRow = Record<string, unknown>;
@@ -7,6 +7,8 @@ export type PhiTableBindingInput = {
     source: PhiProviderResourceSource | null;
     initialQuery?: PhiTableQuery;
     externalQuery?: PhiTableQuery;
+    /** Merged into every query last; see `PhiTableWidgetConfig.fixedFilters`. */
+    fixedFilters?: Readonly<Record<string, PhiTableQueryValue>>;
     externalSearch?: string;
     defaultPageSize?: number;
     refreshKey?: string | number;
@@ -16,7 +18,7 @@ export type PhiTableBindingInput = {
     onMutation?: (result: PhiTableProviderMutationResult) => void;
     validateResource?: (resource: PhiTableProviderResourceDescriptor) => string | null;
 };
-export declare function usePhiTableBinding({ source, initialQuery, externalQuery, externalSearch, defaultPageSize, refreshKey, preserveSelectedRowIdentities, initialExpandedRowIdentities, onData, onMutation, validateResource, }: PhiTableBindingInput): {
+export declare function usePhiTableBinding({ source, initialQuery, externalQuery, fixedFilters, externalSearch, defaultPageSize, refreshKey, preserveSelectedRowIdentities, initialExpandedRowIdentities, onData, onMutation, validateResource, }: PhiTableBindingInput): {
     resource: PhiTableProviderResourceDescriptor | null;
     bindingError: string | null;
     rows: readonly TableRow[];

package/components/tables/client/phi-table-binding.js

@@ -1,7 +1,8 @@
 "use client";
+import { isPhiRecord } from "../../../helpers/is-record";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { PhiTableProviderError, readPhiTableProviderError, readPhiTableProviderMutationResult, readPhiTableProviderQueryResult, validatePhiTableProviderFieldValue, } from "../../../types/table-widget";
-import { movePhiTableBindingRows, movePhiTableBindingTreeRows, patchPhiTableBindingRows, readPhiTableRowIdentity, readPhiTableRowValue, restorePhiTableBindingRowOrder, } from "../../../helpers/table-binding";
+import { mergePhiTableQueryFilters, movePhiTableBindingRows, movePhiTableBindingTreeRows, patchPhiTableBindingRows, readPhiTableRowIdentity, readPhiTableRowValue, restorePhiTableBindingRowOrder, } from "../../../helpers/table-binding";
 import { usePhiTableProvider } from "../../widgets/client/shared/phi-table-provider";
 function validateProviderSummary(resource, summary) {
     if (!summary)
@@ -52,20 +53,17 @@ function createPhiTableQueryKey(query) {
         expandedRowIdentities: query.expandedRowIdentities ?? [],
     });
 }
-function resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities) {
+function resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities, fixedFilters) {
     return {
         ...query,
         ...externalQuery,
         search: externalSearch ?? externalQuery?.search ?? query.search,
         sorts: externalQuery?.sorts ?? query.sorts,
-        filters: {
-            ...(query.filters ?? {}),
-            ...(externalQuery?.filters ?? {}),
-        },
+        filters: mergePhiTableQueryFilters(query, externalQuery, fixedFilters),
         expandedRowIdentities,
     };
 }
-export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, externalSearch, defaultPageSize = 20, refreshKey, preserveSelectedRowIdentities = false, initialExpandedRowIdentities = [], onData, onMutation, validateResource, }) {
+export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, fixedFilters, externalSearch, defaultPageSize = 20, refreshKey, preserveSelectedRowIdentities = false, initialExpandedRowIdentities = [], onData, onMutation, validateResource, }) {
     const { provider, resource, bindingError } = usePhiTableProvider(source);
     const resourceError = resource ? validateResource?.(resource) ?? null : null;
     const [query, setQuery] = useState(() => ({
@@ -127,7 +125,13 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
         });
         return () => { cancelled = true; };
     }, [sourceKey]);
-    const resolvedQuery = useMemo(() => resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities), [expandedRowIdentities, externalQuery, externalSearch, query]);
+    /*
+     * Held by content, not identity: a caller that writes the object inline hands in a new one every
+     * render, and the query effect below would fetch again each time.
+     */
+    const fixedFiltersKey = JSON.stringify(fixedFilters ?? null);
+    const stableFixedFilters = useMemo(() => JSON.parse(fixedFiltersKey) ?? undefined, [fixedFiltersKey]);
+    const resolvedQuery = useMemo(() => resolvePhiTableQuery(query, externalQuery, externalSearch, expandedRowIdentities, stableFixedFilters), [expandedRowIdentities, externalQuery, externalSearch, stableFixedFilters, query]);
     const resolvedQueryKey = useMemo(() => createPhiTableQueryKey(resolvedQuery), [resolvedQuery]);
     const updateMutationTargetPending = useCallback((targetKey, pending) => {
         const current = pendingMutationCountsByTarget.current.get(targetKey) ?? 0;
@@ -233,7 +237,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
                 const resolvedQueryPatch = data.resolvedQuery;
                 if (resolvedQueryPatch) {
                     const canonicalInternalQuery = mergePhiTableQuery(query, resolvedQueryPatch);
-                    const canonicalQuery = resolvePhiTableQuery(canonicalInternalQuery, externalQuery, externalSearch, expandedRowIdentities);
+                    const canonicalQuery = resolvePhiTableQuery(canonicalInternalQuery, externalQuery, externalSearch, expandedRowIdentities, stableFixedFilters);
                     const canonicalQueryKey = createPhiTableQueryKey(canonicalQuery);
                     if (canonicalQueryKey !== resolvedQueryKey) {
                         acceptedResolvedQuery.current = {
@@ -258,7 +262,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
             }
         });
         return () => abortController.abort();
-    }, [applyData, expandedRowIdentities, externalQuery, externalSearch, provider, query, refreshKey, refreshRequest, resolvedQuery, resolvedQueryKey, resource, resourceError, source]);
+    }, [applyData, expandedRowIdentities, externalQuery, externalSearch, provider, query, refreshKey, refreshRequest, resolvedQuery, resolvedQueryKey, resource, resourceError, source, stableFixedFilters]);
     const reload = useCallback(() => setRefreshRequest((current) => ({
         revision: current.revision + 1,
         background: false,
@@ -419,7 +423,7 @@ export function usePhiTableBinding({ source, initialQuery = {}, externalQuery, e
                             ? Array.isArray(value) && value.every((entry) => typeof entry === "string")
                             : action.valueType === "number[]"
                                 ? Array.isArray(value) && value.every((entry) => typeof entry === "number" && Number.isFinite(entry))
-                                : Boolean(value) && typeof value === "object" && !Array.isArray(value);
+                                : isPhiRecord(value);
         if (!valueValid) {
             const valueError = new PhiTableProviderError("action-value-invalid", `Table action "${request.actionKey}" received an incompatible value.`);
             setError(valueError);