@phis/ui 0.2.1 → 0.3.0

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

@@ -1,16 +1,17 @@
-import { resolvePhiBorderWidgetStyle } from "../../helpers/border-widget-style";
+import { resolvePhiSurfaceToneClassName } from "../../types/surface";
+import { PHI_THEME_BORDER_LINE, resolvePhiBorderWidgetStyle } from "../../helpers/border-widget-style";
 import { hasPhiFlag } from "../../helpers/flags";
 import { combinePhiBoxShadows } from "../../helpers/layout-style";
 import { resolveRenderableBlockEffectsAttributes, resolveRenderableBlockEffectsStyle, } from "../../helpers/renderable-block-effects";
 import { resolvePhiShellRegionChrome, resolvePhiShellRegionGroundStyle, resolvePhiShellRegionTypography, resolvePhiShellRegionZIndex, resolvePhiShellSiderCollapsedWidth, resolvePhiShellSiderWidth, } from "../../helpers/shell-region-style";
 import { PhiCmsFlags } from "../../constants/phi-cms";
-import { PHI_COLOR } from "../../theme/antd-css-var-contract";
+import { resolvePhiCmsBorderSource } from "../../types/cms-border-source";
 import { resolvePhiRenderableBlockGeometry } from "../../types/renderable-block-geometry";
 import { createPhiSignalAddress } from "../../types/signals";
+import { readPhiCmsRegionReveal } from "../../helpers/region-page-scope";
 import { resolvePhiPaddingStyle } from "../layouts/phi-layout-contract";
 import { phiRegionUsesShellChromeOverlay } from "../root/phi-shell-chrome-overlay";
-import { phiBackgroundWidgetConfigPaintsGround, resolvePhiBackgroundMotion, resolvePhiBackgroundMotionHostStyle, resolvePhiBackgroundWidgetStyle, } from "../widgets/config/background";
-const PHI_CMS_REGION_FALLBACK_BORDER = `1px solid ${PHI_COLOR.borderSecondary}`;
+import { normalizePhiBackgroundWidgetConfig, phiBackgroundWidgetConfigPaintsGround, resolvePhiBackgroundGroundFilter, resolvePhiBackgroundMotion, resolvePhiBackgroundMotionHostStyle, resolvePhiBackgroundPane, resolvePhiBackgroundWidgetStyle, } from "../widgets/config/background";
 /*
  * The longhands every Region that paints the Shell Chrome Overlay (SHELL.md) carries, read from the
  * custom properties the Root Layout publishes. The colour is here as well as in `shell.css`'s marker
@@ -32,10 +33,7 @@ const PHI_CMS_REGION_SHELL_CHROME_OVERLAY_STYLE = {
 function normalizeCssLength(value) {
     return typeof value === "string" || typeof value === "number" ? value : undefined;
 }
-function isBorderConfig(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-export function resolvePhiCmsRegionShellFamily(regionKey) {
+function resolvePhiCmsRegionShellFamily(regionKey) {
     if (regionKey === "header_top" || regionKey === "header_main" || regionKey === "header_bottom") {
         return "header";
     }
@@ -48,34 +46,39 @@ export function resolvePhiCmsRegionShellFamily(regionKey) {
     return "other";
 }
 /*
- * A configured `border` of `true` or a string is the separator on the edge that faces the Page, which is
- * why it depends on the family; a Border config draws what it says. Nothing configured draws nothing:
- * header, footer and sider separators are never implicit (LAYOUTING.md "Regions").
+ * A Region's edge, from its Surface.
+ *
+ * `theme` is the separator: the Site's own line on the edge that faces the Page, which is why it depends on
+ * the family -- a Header draws it below, a Footer above, a Sider on its inner side, any other Region all
+ * round. `custom` draws the configured border, corners included, as it says. A Region states no corner of
+ * its own otherwise: it spans its part of the frame and has no surface step to take. Nothing configured
+ * draws nothing; separators are never implicit (LAYOUTING.md "Regions").
  */
-function resolveRegionBorderStyle(border, regionKey, family) {
-    if (border == null || border === false) {
-        return {};
+function resolveRegionEdgeStyle(surface, regionKey, family) {
+    const source = resolvePhiCmsBorderSource(surface?.borderSource, surface?.border);
+    if (source === "custom") {
+        return resolvePhiBorderWidgetStyle(surface?.border);
     }
-    if (isBorderConfig(border)) {
-        return resolvePhiBorderWidgetStyle(border);
+    if (source === "none") {
+        return {};
     }
-    const line = typeof border === "string" ? border : PHI_CMS_REGION_FALLBACK_BORDER;
     if (family === "header")
-        return { borderBottom: line };
+        return { borderBottom: PHI_THEME_BORDER_LINE };
     if (family === "footer")
-        return { borderTop: line };
+        return { borderTop: PHI_THEME_BORDER_LINE };
     if (family === "sider") {
-        return regionKey === "sider_left" ? { borderInlineEnd: line } : { borderInlineStart: line };
+        return regionKey === "sider_left"
+            ? { borderInlineEnd: PHI_THEME_BORDER_LINE }
+            : { borderInlineStart: PHI_THEME_BORDER_LINE };
     }
-    return { border: line };
+    return { border: PHI_THEME_BORDER_LINE };
 }
-function resolveRegionBorderLine(border) {
-    if (border === true)
-        return PHI_CMS_REGION_FALLBACK_BORDER;
-    if (typeof border === "string")
-        return border;
-    if (isBorderConfig(border)) {
-        const line = resolvePhiBorderWidgetStyle(border).border;
+function resolveRegionBorderLine(surface) {
+    const source = resolvePhiCmsBorderSource(surface?.borderSource, surface?.border);
+    if (source === "theme")
+        return PHI_THEME_BORDER_LINE;
+    if (source === "custom") {
+        const line = resolvePhiBorderWidgetStyle(surface?.border).border;
         return typeof line === "string" ? line : undefined;
     }
     return undefined;
@@ -99,39 +102,72 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
     const siderWidth = geometry.inline.size?.css ?? resolvePhiShellSiderWidth(shellTheme);
     const siderCollapsedWidth = normalizeCssLength(config.collapsedWidth) ?? resolvePhiShellSiderCollapsedWidth(shellTheme);
     const top = normalizeCssLength(config.offsetTop) ?? 0;
-    const sticky = config.sticky === true;
+    const topCss = typeof top === "number" ? `${top}px` : top;
+    const sticky = hasPhiFlag(config.flags, PhiCmsFlags.Sticky);
+    // A preview shows the Region where it stands, so an author can see what they are editing.
+    const reveal = previewMode ? "always" : readPhiCmsRegionReveal(regionKey, config);
     /*
      * Full height is a Sider's behaviour and nobody else's (LAYOUTING.md: "where the Region family
      * supports it"). The static renderer used to give every Region kind the viewport-height `calc` when
      * the flag was set, the client one only a Sider.
      */
-    const fullHeight = isSider && config.fullHeight === true;
-    const stuck = isHeader ? sticky : isSider && (sticky || fullHeight);
+    const fullHeight = isSider && hasPhiFlag(config.flags, PhiCmsFlags.FullHeight);
+    /*
+     * A revealing `header_top` sticks whatever its flag says: coming back into view at the top edge is what
+     * revealing means, and only a sticky band has a top edge to come back to.
+     */
+    const stuck = isHeader ? sticky || reveal !== "always" : isSider && (sticky || fullHeight);
+    /*
+     * The Header bands below `header_top` stick under it while it is in view and close up when it leaves.
+     * `--phi-shell-header-top-stack` is how much of the viewport's top it holds right now; only a
+     * `scroll-up` band ever publishes it (SHELL.md "Region visibility per Page"), so for every other Shell
+     * it is unset and the offset is the one configured.
+     */
+    const stuckTop = !stuck
+        ? undefined
+        : isHeader && regionKey !== "header_top"
+            ? `calc(${topCss} + var(--phi-shell-header-top-stack, 0px))`
+            : top;
     const blockSize = geometry.block.size?.css;
     const fullHeightSize = fullHeight && !blockSize
-        ? `calc(100dvh - ${typeof top === "number" ? `${top}px` : top})`
+        ? `calc(100dvh - ${topCss})`
         : blockSize;
-    const zIndex = config.zIndex ?? resolvePhiShellRegionZIndex(regionKey, config.fullHeight === true);
+    const zIndex = config.zIndex ?? resolvePhiShellRegionZIndex(regionKey, hasPhiFlag(config.flags, PhiCmsFlags.FullHeight));
     /*
      * A Background config that paints nothing is not an authored ground. The Builder writes one onto every
      * Region draft it persists, so its presence would otherwise mean "authored" for every Region an author
      * has ever opened.
      */
-    const backgroundConfig = phiBackgroundWidgetConfigPaintsGround(config.backgroundConfig)
-        ? config.backgroundConfig
+    const surface = config.surface ?? null;
+    const surfaceBackground = surface?.background
+        ? normalizePhiBackgroundWidgetConfig(surface.background)
         : null;
+    const backgroundConfig = phiBackgroundWidgetConfigPaintsGround(surfaceBackground) ? surfaceBackground : null;
+    /*
+     * A pane on a Region without a ground of its own frosts the Shell's ground for this Region -- the
+     * Theme's record, or the family's fallback -- which is what glass on a bare Header has always meant.
+     * A Region that paints its own ground carries its pane inside that Background, as every Surface does.
+     */
+    const shellPane = backgroundConfig == null ? resolvePhiBackgroundPane(surfaceBackground) : null;
     const backgroundMoves = animatesBackground &&
         backgroundConfig != null &&
         resolvePhiBackgroundMotion(backgroundConfig) != null;
-    const backgroundStyle = backgroundConfig == null
+    const groundFilter = backgroundConfig == null ? null : resolvePhiBackgroundGroundFilter(backgroundConfig);
+    const ground = backgroundConfig != null && groundFilter != null && !backgroundMoves
+        ? {
+            paint: resolvePhiBackgroundWidgetStyle({ ...backgroundConfig, filter: null, motion: null }),
+            filter: groundFilter,
+            motion: null,
+        }
+        : null;
+    const backgroundStyle = backgroundConfig == null || ground != null
         ? null
         : backgroundMoves
-            ? resolvePhiBackgroundMotionHostStyle({ ...backgroundConfig, effect: null })
-            : resolvePhiBackgroundWidgetStyle({ ...backgroundConfig, effect: null });
+            ? resolvePhiBackgroundMotionHostStyle(backgroundConfig)
+            : resolvePhiBackgroundWidgetStyle(backgroundConfig);
     const chromeInput = {
-        background: typeof config.background === "string" ? config.background : undefined,
-        shadow: config.shadow,
-        effect: config.effect,
+        shadow: surface?.shadow ?? undefined,
+        effect: shellPane ?? undefined,
         tokens: paint.kind === "live" ? paint.tokens : undefined,
     };
     const chrome = {
@@ -151,7 +187,7 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
     const usesShellChromeOverlay = phiRegionUsesShellChromeOverlay({
         regionKey,
         backgroundConfig,
-        effect: config.effect,
+        pane: shellPane,
         grounds: [chrome.light.background, chrome.dark.background],
     });
     /*
@@ -199,7 +235,6 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
         collapsedSizeHint: config.collapsedSizeHint,
         zIndex,
         opacity: config.opacity,
-        effect: config.effect,
         effects: config.effects,
     };
     const effectsAttributes = resolveRenderableBlockEffectsAttributes(effectsConfig);
@@ -242,12 +277,10 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
         ...modeStyle,
         ...(backgroundStyle ?? {}),
         position: stuck ? "sticky" : "relative",
-        top: stuck ? top : undefined,
-        insetBlockStart: isHeader && stuck ? top : undefined,
+        top: stuckTop,
+        insetBlockStart: isHeader ? stuckTop : undefined,
         zIndex,
         ...geometryStyle,
-        // The flat radius first, so a Border config's per-corner radii land on top of it.
-        borderRadius: normalizeCssLength(config.borderRadius),
         color: liveChrome ? liveChrome.color : "var(--phi-region-color)",
         ...effectStyle,
         ...groundStyle,
@@ -255,26 +288,37 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
         boxShadow: combinePhiBoxShadows(typeof backgroundStyle?.boxShadow === "string" ? backgroundStyle.boxShadow : undefined, paintedChrome.effectStyle?.boxShadow, paintedChrome.shadow),
         ...(typography.fontSize ? { fontSize: typography.fontSize } : {}),
         ...(typography.lineHeight ? { lineHeight: typography.lineHeight } : {}),
-        ...resolveRegionBorderStyle(config.border, regionKey, family),
+        ...resolveRegionEdgeStyle(surface, regionKey, family),
         ...(config.opacity == null ? {} : { opacity: config.opacity }),
         ...(enabled ? {} : { opacity: Math.min(config.opacity ?? 1, 0.5), pointerEvents: "none" }),
         ...(visibility === "collapsed" ? { overflow: "hidden" } : {}),
         ...resolveRenderableBlockEffectsStyle(effectsConfig),
-        ...(backgroundMoves ? { isolation: "isolate" } : {}),
+        ...(backgroundMoves || ground != null ? { isolation: "isolate" } : {}),
         ...style,
         margin: 0,
         ...(!isSider && geometry.inline.max != null ? { marginInline: "auto" } : {}),
+        /*
+         * A `hover` band takes no room: its own height comes off again below it, so its grid track collapses
+         * and the Page starts at the top. What the client measured stands in for a height nobody stated.
+         */
+        ...(reveal === "hover"
+            ? { marginBlockEnd: `calc(-1 * ${blockSize ?? "var(--phi-region-reveal-extent, 0px)"})` }
+            : {}),
+        ...(reveal === "always" ? {} : { "--phi-region-reveal-offset": topCss }),
     };
     return {
         family,
         element: isHeader ? "header" : family === "footer" ? "footer" : isSider ? "aside" : "div",
         visibility,
         enabled,
+        reveal,
         siderWidth,
         siderCollapsedWidth,
+        tone: surface?.tone ?? null,
         backgroundConfig,
         animatesBackground: backgroundMoves,
-        borderLine: resolveRegionBorderLine(config.border),
+        ground,
+        borderLine: resolveRegionBorderLine(surface),
         effectsConfig,
         attributes: {
             "data-phi-region-key": regionKey,
@@ -285,8 +329,11 @@ export function resolvePhiCmsRegionShell({ regionKey, config, shellTheme, paint,
             "data-phi-block-visibility": visibility,
             "data-phi-viewport-flags": viewportFlags,
             "data-phi-block-enabled": enabled ? "true" : "false",
+            "data-phi-region-reveal": reveal === "always" ? undefined : reveal,
             ...effectsAttributes,
-            className: ["phi-cms-region-shell", className].filter(Boolean).join(" "),
+            className: ["phi-cms-region-shell", resolvePhiSurfaceToneClassName(surface?.tone), className]
+                .filter(Boolean)
+                .join(" "),
         },
         style: rootStyle,
         contentStyle: resolvePhiPaddingStyle({

package/components/regions/phi-cms-region-static.js

@@ -1,5 +1,7 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { resolvePhiCmsRegionShell } from "./phi-cms-region-shell";
+import { PhiSurfaceGroundLayer } from "../surface/phi-surface-ground";
+import { PhiSurfaceTone } from "../surface/phi-surface-tone";
 /**
  * A Region with nothing to do after it has rendered. Everything it draws comes from the Region-shell
  * resolver it shares with the client renderer; it does not know the colour mode, so it publishes both
@@ -20,5 +22,6 @@ export function PhiCmsRegionStatic({ children, className, regionKey, config = {}
         return null;
     }
     const Element = shell.element;
-    return (_jsx(Element, { ...shell.attributes, style: shell.style, children: _jsx("div", { className: "phi-cms-region-shell__content", style: shell.contentStyle, children: children }) }));
+    const element = (_jsxs(Element, { ...shell.attributes, style: shell.style, children: [_jsx(PhiSurfaceGroundLayer, { ground: shell.ground }), _jsx("div", { className: "phi-cms-region-shell__content", style: shell.contentStyle, children: children })] }));
+    return shell.tone ? _jsx(PhiSurfaceTone, { tone: shell.tone, children: element }) : element;
 }

package/components/regions/presets/content-entry-editor-page-tree.d.ts

@@ -0,0 +1,48 @@
+import type { PhiContentEntryKind } from "../../../constants/content-entry-kinds";
+import type { PhiCmsPageNode, PhiResolvedCmsPageTree } from "../../../types/cms";
+import type { PhiBlockRuntime, PhiRuntimeModuleId } from "../../../types";
+import type { PhiFormId } from "../../../types/form-id";
+/**
+ * The words of an editor Page that differ by kind; everything else is the shared Label Set's.
+ *
+ * Handed in by the kind's Module from its own Label Set, already translated: "New news entry" and "New
+ * blog post" are not one sentence with a noun swapped, and a translator sees them as the two they are.
+ */
+export type PhiContentEntryKindEditorLabels = {
+    /** The Table's name in the Builder's layer tree: "news entries". */
+    widgetLabel: string;
+    /** The edit dialog's title: "News entry". */
+    entryTitle: string;
+    /** The create dialog's title: "New news entry". */
+    createTitle: string;
+    /** What the empty Table says: "No news entries yet." */
+    emptyTitle: string;
+};
+/**
+ * The editor Page of one content kind: the Site's entries in a Table, and the three dialogs one writes in
+ * (`CONTENT_ENTRIES.md`).
+ *
+ * The Table is the core Widget bound to Core's entries Provider under the kind's resource, which is what
+ * makes the same rows placeable on any Page a Site composes -- the Page here is one placement, not the
+ * surface itself. Who may see them is decided by the endpoint behind the Provider, so a Table on a Page
+ * nobody may edit answers nothing rather than being kept out.
+ *
+ * Withdrawing, submitting and deleting are row actions: they state nothing, so they need no Form. Writing
+ * an entry and publishing one do state something and are Forms, in the dialogs below.
+ */
+export declare function buildPhiContentEntryEditorPageTree({ page, runtime, kind, ownerModuleId, presetKey, formIds, kindLabels, }: {
+    page: PhiCmsPageNode;
+    runtime: PhiBlockRuntime;
+    kind: PhiContentEntryKind;
+    /** The kind's Module, whose preset this Page is: with `presetKey`, the identity of every node on it. */
+    ownerModuleId: PhiRuntimeModuleId;
+    presetKey: string;
+    /** The Module's Forms (`definePhiContentEntryForms`). */
+    formIds: {
+        entry: PhiFormId;
+        publication: PhiFormId;
+        curation: PhiFormId;
+        category: PhiFormId;
+    };
+    kindLabels: PhiContentEntryKindEditorLabels;
+}): Promise<PhiResolvedCmsPageTree>;